@prisma-next/extension-pgvector 0.5.0-dev.8 → 0.5.0-dev.81

package/src/core/descriptor-meta.ts

@@ -1,38 +1,65 @@
 import type { SqlOperationDescriptor } from '@prisma-next/sql-operations';
+import {
+  buildOperation,
+  type CodecExpression,
+  type Expression,
+  refsOf,
+  toExpr,
+} from '@prisma-next/sql-relational-core/expression';
 import type { CodecTypes } from '../types/codec-types';
 import { pgvectorAuthoringTypes } from './authoring';
-import { codecDefinitions } from './codecs';
+import { pgvectorCodecRegistry } from './registry';
 
 const pgvectorTypeId = 'pg/vector@1' as const;
 
-export const pgvectorQueryOperations: readonly SqlOperationDescriptor[] = [
-  {
-    method: 'cosineDistance',
-    args: [
-      { codecId: pgvectorTypeId, nullable: false },
-      { codecId: pgvectorTypeId, nullable: false },
-    ],
-    returns: { codecId: 'pg/float8@1', nullable: false },
-    lowering: {
-      targetFamily: 'sql',
-      strategy: 'function',
-      template: '{{self}} <=> {{arg0}}',
+type CodecTypesBase = Record<string, { readonly input: unknown; readonly output: unknown }>;
+
+export function pgvectorQueryOperations<
+  CT extends CodecTypesBase,
+>(): readonly SqlOperationDescriptor[] {
+  return [
+    {
+      method: 'cosineDistance',
+      self: { codecId: pgvectorTypeId },
+      impl: (
+        self: CodecExpression<'pg/vector@1', boolean, CT>,
+        other: CodecExpression<'pg/vector@1', boolean, CT>,
+      ): Expression<{ codecId: 'pg/float8@1'; nullable: false }> => {
+        const selfRefs = refsOf(self);
+        return buildOperation({
+          method: 'cosineDistance',
+          args: [toExpr(self, pgvectorTypeId, selfRefs), toExpr(other, pgvectorTypeId, selfRefs)],
+          returns: { codecId: 'pg/float8@1', nullable: false },
+          lowering: {
+            targetFamily: 'sql',
+            strategy: 'function',
+            template: '{{self}} <=> {{arg0}}',
+          },
+        });
+      },
     },
-  },
-  {
-    method: 'cosineSimilarity',
-    args: [
-      { codecId: pgvectorTypeId, nullable: false },
-      { codecId: pgvectorTypeId, nullable: false },
-    ],
-    returns: { codecId: 'pg/float8@1', nullable: false },
-    lowering: {
-      targetFamily: 'sql',
-      strategy: 'function',
-      template: '1 - ({{self}} <=> {{arg0}})',
+    {
+      method: 'cosineSimilarity',
+      self: { codecId: pgvectorTypeId },
+      impl: (
+        self: CodecExpression<'pg/vector@1', boolean, CT>,
+        other: CodecExpression<'pg/vector@1', boolean, CT>,
+      ): Expression<{ codecId: 'pg/float8@1'; nullable: false }> => {
+        const selfRefs = refsOf(self);
+        return buildOperation({
+          method: 'cosineSimilarity',
+          args: [toExpr(self, pgvectorTypeId, selfRefs), toExpr(other, pgvectorTypeId, selfRefs)],
+          returns: { codecId: 'pg/float8@1', nullable: false },
+          lowering: {
+            targetFamily: 'sql',
+            strategy: 'function',
+            template: '1 - ({{self}} <=> {{arg0}})',
+          },
+        });
+      },
     },
-  },
-];
+  ];
+}
 
 const pgvectorPackMetaBase = {
   kind: 'extension',
@@ -50,7 +77,7 @@ const pgvectorPackMetaBase = {
   },
   types: {
     codecTypes: {
-      codecInstances: Object.values(codecDefinitions).map((def) => def.codec),
+      codecDescriptors: Array.from(pgvectorCodecRegistry.values()),
       import: {
         package: '@prisma-next/extension-pgvector/codec-types',
         named: 'CodecTypes',

package/src/core/migrations.ts

@@ -0,0 +1,125 @@
+/**
+ * pgvector contract space — baseline migration package.
+ *
+ * An extension's `contractSpace.migrations` is a list of in-memory
+ * `MigrationPackage` values whose `ops` carry framework-level
+ * `MigrationPlanOperation`s. The SQL family runner reads the additional
+ * runtime fields (`target`, `precheck`, `execute`, `postcheck`) at
+ * apply time.
+ *
+ * Ships a single baseline migration whose only op is
+ * {@link installVectorExtensionOp} — it carries the
+ * `CREATE EXTENSION IF NOT EXISTS vector` DDL plus a postcondition that
+ * confirms the extension landed. Mirrors the prior
+ * `databaseDependencies.init[0]` shape (precheck / execute / postcheck)
+ * but as a `MigrationPackage` op so the framework's per-space runner /
+ * verifier can manage it the same way it manages an application's own
+ * migrations.
+ *
+ * The op carries the stable `pgvector:install-vector-v1` invariantId —
+ * once published it is immutable.
+ */
+
+import type { SqlMigrationPlanOperation } from '@prisma-next/family-sql/control';
+import type {
+  ContractSpaceHeadRef,
+  MigrationPackage,
+  MigrationPlanOperation,
+} from '@prisma-next/framework-components/control';
+import { computeMigrationHash } from '@prisma-next/migration-tools/hash';
+import { PGVECTOR_STORAGE_HASH, pgvectorContract } from './contract';
+import { PGVECTOR_BASELINE_MIGRATION_NAME, PGVECTOR_INVARIANTS } from './contract-space-constants';
+
+/**
+ * Postgres-style `target.details` shape the SQL runner consumes when
+ * executing extension-space ops. pgvector targets only Postgres;
+ * locking the target id here keeps the per-op `target` literal narrow
+ * without coupling to the Postgres adapter package's
+ * `PostgresPlanTargetDetails`.
+ */
+type PostgresTargetDetails = {
+  readonly schema: string;
+  readonly objectType: 'extension';
+  readonly name: string;
+};
+
+const installVectorExtensionOp: SqlMigrationPlanOperation<unknown> = {
+  id: 'pgvector.install-vector-extension',
+  label: 'Enable extension "vector"',
+  operationClass: 'additive',
+  invariantId: PGVECTOR_INVARIANTS.installVector,
+  target: {
+    id: 'postgres',
+    details: {
+      schema: 'public',
+      objectType: 'extension',
+      name: 'vector',
+    } satisfies PostgresTargetDetails,
+  },
+  precheck: [
+    {
+      description: 'verify extension "vector" is not already enabled',
+      sql: "SELECT NOT EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'vector')",
+    },
+  ],
+  execute: [
+    {
+      description: 'create extension "vector"',
+      sql: 'CREATE EXTENSION IF NOT EXISTS vector',
+    },
+  ],
+  postcheck: [
+    {
+      description: 'confirm extension "vector" is enabled',
+      sql: "SELECT EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'vector')",
+    },
+  ],
+};
+
+const pgvectorBaselineOps: readonly MigrationPlanOperation[] = [installVectorExtensionOp];
+
+/** Sorted list of invariantIds the baseline migration provides. */
+export const PGVECTOR_BASELINE_INVARIANTS: readonly string[] = (() => {
+  const ids = pgvectorBaselineOps
+    .map((op) => op.invariantId)
+    .filter((id): id is string => typeof id === 'string');
+  return [...new Set(ids)].sort();
+})();
+
+const baselineMetadataWithoutHash: Omit<MigrationPackage['metadata'], 'migrationHash'> = {
+  from: null,
+  to: PGVECTOR_STORAGE_HASH,
+  fromContract: null,
+  toContract: pgvectorContract,
+  hints: { used: [], applied: [], plannerVersion: '2.0.0' },
+  labels: [],
+  providedInvariants: PGVECTOR_BASELINE_INVARIANTS,
+  createdAt: '2026-06-01T00:00:00.000Z',
+};
+
+/**
+ * Baseline migration package the descriptor publishes via
+ * `contractSpace.migrations`. The framework's emitter writes this to
+ * `migrations/pgvector/<dirName>/{manifest,ops,contract}.json` in the
+ * user's repo at `migrate` time.
+ */
+export const pgvectorBaselineMigration: MigrationPackage = {
+  dirName: PGVECTOR_BASELINE_MIGRATION_NAME,
+  metadata: {
+    ...baselineMetadataWithoutHash,
+    migrationHash: computeMigrationHash(baselineMetadataWithoutHash, pgvectorBaselineOps),
+  },
+  ops: pgvectorBaselineOps,
+};
+
+/**
+ * Pinned head ref the descriptor publishes. The framework writes this
+ * verbatim to `migrations/pgvector/refs/head.json` (with `invariants`
+ * sorted alphabetically per the canonicalisation rules); the runner's
+ * `findPathWithDecision` step consults `head.json` to decide which
+ * migrations need to apply.
+ */
+export const pgvectorHeadRef: ContractSpaceHeadRef = {
+  hash: PGVECTOR_STORAGE_HASH,
+  invariants: PGVECTOR_BASELINE_INVARIANTS,
+};

package/src/core/registry.ts

@@ -0,0 +1,11 @@
+import { buildCodecDescriptorRegistry } from '@prisma-next/sql-relational-core/codec-descriptor-registry';
+import type { CodecDescriptorRegistry } from '@prisma-next/sql-relational-core/query-lane-context';
+import { codecDescriptors } from './codecs';
+
+/**
+ * Registry of every codec descriptor shipped by `@prisma-next/extension-pgvector`.
+ *
+ * Public consumer surface for the pgvector codec set. Currently a single entry (`pg/vector@1`); the registry shape stays consistent with the other codec-shipping packages so consumers don't need to special-case extensions. See ADR 208.
+ */
+export const pgvectorCodecRegistry: CodecDescriptorRegistry =
+  buildCodecDescriptorRegistry(codecDescriptors);

package/src/exports/column-types.ts

@@ -1,16 +1,14 @@
 /**
  * Column type descriptors for pgvector extension.
  *
- * These descriptors provide both codecId and nativeType for use in contract authoring.
- * They are derived from the same source of truth as codec definitions and manifests.
+ * These descriptors provide both codecId and nativeType for use in contract authoring. They are derived from the same source of truth as codec definitions and manifests.
  */
 
-import type { ColumnTypeDescriptor } from '@prisma-next/contract-authoring';
+import type { ColumnTypeDescriptor } from '@prisma-next/framework-components/codec';
 import { VECTOR_CODEC_ID, VECTOR_MAX_DIM } from '../core/constants';
 
 /**
- * Static vector column descriptor without dimension.
- * Use `vector(N)` for dimensioned vectors that produce `vector(N)` DDL.
+ * Static vector column descriptor without dimension. Use `vector(N)` for dimensioned vectors that produce `vector(N)` DDL.
  */
 export const vectorColumn = {
   codecId: VECTOR_CODEC_ID,
@@ -25,7 +23,6 @@ export const vectorColumn = {
  * .column('embedding', { type: vector(1536), nullable: false })
  * // Produces: nativeType: 'vector', typeParams: { length: 1536 }
  * ```
- *
  * @param length - The dimension of the vector (e.g., 1536 for OpenAI embeddings)
  * @returns A column type descriptor with `typeParams.length` set
  * @throws {RangeError} If length is not an integer in the range [1, VECTOR_MAX_DIM]

package/src/exports/control.ts

@@ -1,9 +1,36 @@
+/**
+ * Control-plane descriptor for the pgvector extension.
+ *
+ * Exposes a `contractSpace` so the framework's per-space planner /
+ * runner / verifier (project: extension-contract-spaces, M1+M2)
+ * manages the pgvector extension's database scaffolding the same way
+ * it manages an application's own schema. The descriptor is consumed
+ * by the framework only at authoring time (`migrate`); apply / verify
+ * paths read the user's repo (`migrations/pgvector/...`) instead — see
+ * project spec NFR3 / FR2 / FR10.
+ *
+ * `databaseDependencies` is intentionally absent — pgvector was
+ * migrated off the legacy `databaseDependencies.init` mechanism in M4
+ * (project spec FR13). The `CREATE EXTENSION IF NOT EXISTS vector`
+ * DDL the legacy entry carried now lives as the body of the
+ * `installVectorExtension` op inside the baseline migration package
+ * (`../core/migrations.ts`). Presence of `contractSpace` is the
+ * shipping-strategy gate: the framework loads the contract space and
+ * ignores any `databaseDependencies` block (project plan §
+ * "Shipping Strategy"). M5 removes the field at the framework level.
+ */
+
+import type { Contract } from '@prisma-next/contract/types';
 import type {
   CodecControlHooks,
-  ComponentDatabaseDependencies,
   SqlControlExtensionDescriptor,
 } from '@prisma-next/family-sql/control';
+import type { ContractSpace } from '@prisma-next/framework-components/control';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
+import { pgvectorContract } from '../core/contract';
+import { PGVECTOR_SPACE_ID } from '../core/contract-space-constants';
 import { pgvectorPackMeta, pgvectorQueryOperations } from '../core/descriptor-meta';
+import { pgvectorBaselineMigration, pgvectorHeadRef } from '../core/migrations';
 
 const PGVECTOR_CODEC_ID = 'pg/vector@1' as const;
 
@@ -28,44 +55,16 @@ const vectorControlPlaneHooks: CodecControlHooks = {
   resolveIdentityValue: ({ typeParams }) => buildVectorIdentityValue(typeParams),
 };
 
-const pgvectorDatabaseDependencies: ComponentDatabaseDependencies<unknown> = {
-  init: [
-    {
-      id: 'postgres.extension.vector',
-      label: 'Enable vector extension',
-      install: [
-        {
-          id: 'extension.vector',
-          label: 'Enable extension "vector"',
-          summary: 'Ensures the vector extension is available for pgvector operations',
-          operationClass: 'additive',
-          target: { id: 'postgres' },
-          precheck: [
-            {
-              description: 'verify extension "vector" is not already enabled',
-              sql: "SELECT NOT EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'vector')",
-            },
-          ],
-          execute: [
-            {
-              description: 'create extension "vector"',
-              sql: 'CREATE EXTENSION IF NOT EXISTS vector',
-            },
-          ],
-          postcheck: [
-            {
-              description: 'confirm extension "vector" is enabled',
-              sql: "SELECT EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'vector')",
-            },
-          ],
-        },
-      ],
-    },
-  ],
+const pgvectorContractSpace: ContractSpace<Contract<SqlStorage>> = {
+  contractJson: pgvectorContract,
+  migrations: [pgvectorBaselineMigration],
+  headRef: pgvectorHeadRef,
 };
 
 const pgvectorExtensionDescriptor: SqlControlExtensionDescriptor<'postgres'> = {
   ...pgvectorPackMeta,
+  id: PGVECTOR_SPACE_ID,
+  contractSpace: pgvectorContractSpace,
   types: {
     ...pgvectorPackMeta.types,
     codecTypes: {
@@ -75,8 +74,7 @@ const pgvectorExtensionDescriptor: SqlControlExtensionDescriptor<'postgres'> = {
       },
     },
   },
-  queryOperations: () => pgvectorQueryOperations,
-  databaseDependencies: pgvectorDatabaseDependencies,
+  queryOperations: () => pgvectorQueryOperations(),
   create: () => ({
     familyId: 'sql' as const,
     targetId: 'postgres' as const,

package/src/exports/runtime.ts

@@ -1,42 +1,6 @@
-import { createCodecRegistry } from '@prisma-next/sql-relational-core/ast';
-import type {
-  RuntimeParameterizedCodecDescriptor,
-  SqlRuntimeExtensionDescriptor,
-} from '@prisma-next/sql-runtime';
-import { type as arktype } from 'arktype';
-import { codecDefinitions } from '../core/codecs';
-import { VECTOR_CODEC_ID, VECTOR_MAX_DIM } from '../core/constants';
+import type { SqlRuntimeExtensionDescriptor } from '@prisma-next/sql-runtime';
 import { pgvectorPackMeta, pgvectorQueryOperations } from '../core/descriptor-meta';
-
-const vectorParamsSchema = arktype({
-  length: 'number',
-}).narrow((params, ctx) => {
-  const { length } = params;
-  if (!Number.isInteger(length)) {
-    return ctx.mustBe('an integer');
-  }
-  if (length < 1 || length > VECTOR_MAX_DIM) {
-    return ctx.mustBe(`in the range [1, ${VECTOR_MAX_DIM}]`);
-  }
-  return true;
-});
-
-const parameterizedCodecDescriptors = [
-  {
-    codecId: VECTOR_CODEC_ID,
-    paramsSchema: vectorParamsSchema,
-  },
-] as const satisfies ReadonlyArray<
-  RuntimeParameterizedCodecDescriptor<{ readonly length: number }>
->;
-
-function createPgvectorCodecRegistry() {
-  const registry = createCodecRegistry();
-  for (const def of Object.values(codecDefinitions)) {
-    registry.register(def.codec);
-  }
-  return registry;
-}
+import { pgvectorCodecRegistry } from '../core/registry';
 
 const pgvectorRuntimeDescriptor: SqlRuntimeExtensionDescriptor<'postgres'> = {
   kind: 'extension' as const,
@@ -44,9 +8,14 @@ const pgvectorRuntimeDescriptor: SqlRuntimeExtensionDescriptor<'postgres'> = {
   version: pgvectorPackMeta.version,
   familyId: 'sql' as const,
   targetId: 'postgres' as const,
-  codecs: createPgvectorCodecRegistry,
-  queryOperations: () => pgvectorQueryOperations,
-  parameterizedCodecs: () => parameterizedCodecDescriptors,
+  // Expose the unified descriptor list so `extractCodecLookup` reads `targetTypes` / `meta` / `renderOutputType` directly off the descriptors and materializes the representative `Codec` for the SQL renderer's cast-policy lookup.
+  types: {
+    codecTypes: {
+      codecDescriptors: Array.from(pgvectorCodecRegistry.values()),
+    },
+  },
+  codecs: () => Array.from(pgvectorCodecRegistry.values()),
+  queryOperations: () => pgvectorQueryOperations(),
   create() {
     return {
       familyId: 'sql' as const,
@@ -55,4 +24,5 @@ const pgvectorRuntimeDescriptor: SqlRuntimeExtensionDescriptor<'postgres'> = {
   },
 };
 
+export { pgvectorCodecRegistry };
 export default pgvectorRuntimeDescriptor;

package/src/types/operation-types.ts

@@ -1,4 +1,7 @@
 import type { SqlQueryOperationTypes } from '@prisma-next/sql-contract/types';
+import type { CodecExpression, Expression } from '@prisma-next/sql-relational-core/expression';
+
+type CodecTypesBase = Record<string, { readonly input: unknown; readonly output: unknown }>;
 
 /**
  * Operation type definitions for pgvector extension.
@@ -10,40 +13,31 @@ import type { SqlQueryOperationTypes } from '@prisma-next/sql-contract/types';
 export type OperationTypes = {
   readonly 'pg/vector@1': {
     readonly cosineDistance: {
-      readonly args: readonly [{ readonly codecId: 'pg/vector@1'; readonly nullable: false }];
-      readonly returns: { readonly codecId: 'pg/float8@1'; readonly nullable: false };
-      readonly lowering: {
-        readonly targetFamily: 'sql';
-        readonly strategy: 'function';
-        readonly template: string;
-      };
+      readonly self: { readonly codecId: 'pg/vector@1' };
     };
     readonly cosineSimilarity: {
-      readonly args: readonly [{ readonly codecId: 'pg/vector@1'; readonly nullable: false }];
-      readonly returns: { readonly codecId: 'pg/float8@1'; readonly nullable: false };
-      readonly lowering: {
-        readonly targetFamily: 'sql';
-        readonly strategy: 'function';
-        readonly template: string;
-      };
+      readonly self: { readonly codecId: 'pg/vector@1' };
     };
   };
 };
 
 /** Flat operation signatures for the query builder. */
-export type QueryOperationTypes = SqlQueryOperationTypes<{
-  readonly cosineDistance: {
-    readonly args: readonly [
-      { readonly codecId: 'pg/vector@1'; readonly nullable: boolean },
-      { readonly codecId: 'pg/vector@1'; readonly nullable: boolean },
-    ];
-    readonly returns: { readonly codecId: 'pg/float8@1'; readonly nullable: false };
-  };
-  readonly cosineSimilarity: {
-    readonly args: readonly [
-      { readonly codecId: 'pg/vector@1'; readonly nullable: boolean },
-      { readonly codecId: 'pg/vector@1'; readonly nullable: boolean },
-    ];
-    readonly returns: { readonly codecId: 'pg/float8@1'; readonly nullable: false };
-  };
-}>;
+export type QueryOperationTypes<CT extends CodecTypesBase> = SqlQueryOperationTypes<
+  CT,
+  {
+    readonly cosineDistance: {
+      readonly self: { readonly codecId: 'pg/vector@1' };
+      readonly impl: (
+        self: CodecExpression<'pg/vector@1', boolean, CT>,
+        other: CodecExpression<'pg/vector@1', boolean, CT>,
+      ) => Expression<{ codecId: 'pg/float8@1'; nullable: false }>;
+    };
+    readonly cosineSimilarity: {
+      readonly self: { readonly codecId: 'pg/vector@1' };
+      readonly impl: (
+        self: CodecExpression<'pg/vector@1', boolean, CT>,
+        other: CodecExpression<'pg/vector@1', boolean, CT>,
+      ) => Expression<{ codecId: 'pg/float8@1'; nullable: false }>;
+    };
+  }
+>;

package/dist/codec-types-BifaP625.d.mts

@@ -1,27 +0,0 @@
-import * as _prisma_next_sql_relational_core_ast0 from "@prisma-next/sql-relational-core/ast";
-
-//#region src/core/codecs.d.ts
-
-/**
- * Vector codec implementation for pgvector extension.
- *
- * Provides encoding/decoding for the `vector` PostgreSQL type.
- * Wire format is a string like `[1,2,3]` (PostgreSQL vector text format).
- */
-declare const codecs: _prisma_next_sql_relational_core_ast0.CodecDefBuilder<{} & Record<"vector", _prisma_next_sql_relational_core_ast0.Codec<"pg/vector@1", readonly ["equality"], string, number[], Record<string, unknown>, unknown>>>;
-type CodecTypes$1 = typeof codecs.CodecTypes;
-//#endregion
-//#region src/types/codec-types.d.ts
-/**
- * Type-level branded vector.
- *
- * The runtime values are plain number arrays, but parameterized column typing can
- * carry the dimension at the type level (e.g. Vector<1536>).
- */
-type Vector<N extends number = number> = number[] & {
-  readonly __vectorLength?: N;
-};
-type CodecTypes = CodecTypes$1;
-//#endregion
-export { Vector as n, CodecTypes as t };
-//# sourceMappingURL=codec-types-BifaP625.d.mts.map

package/dist/codec-types-BifaP625.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"codec-types-BifaP625.d.mts","names":[],"sources":["../src/core/codecs.ts","../src/types/codec-types.ts"],"sourcesContent":[],"mappings":";;;;;;;AAqEY;;;cAAN,MAAM,EAAA,qCAAA,CAAA,eAAA,CAAA,CAAA,CAAA,GAAA,MAAA,CAAA,QAAA,EAAA,qCAAA,CAAA,KAAA,CAAA,aAAA,EAAA,SAAA,CAAA,UAAA,CAAA,EAAA,MAAA,EAAA,MAAA,EAAA,EAAA,MAAA,CAAA,MAAA,EAAA,OAAA,CAAA,EAAA,OAAA,CAAA,CAAA,CAAA;KAOA,YAAA,UAAoB,MAAA,CAAO;;;AAAvC;;;;AC3DA;AAEA;KAFY;4BAA2E;;KAE3E,UAAA,GAAa"}