@prisma-next/extension-pgvector 0.5.0-dev.9 → 0.6.0-dev.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/README.md +23 -6
  2. package/dist/codec-types-CQubO6uQ.d.mts +63 -0
  3. package/dist/codec-types-CQubO6uQ.d.mts.map +1 -0
  4. package/dist/codec-types.d.mts +1 -1
  5. package/dist/codec-types.mjs +1 -1
  6. package/dist/column-types.d.mts +2 -5
  7. package/dist/column-types.d.mts.map +1 -1
  8. package/dist/column-types.mjs +4 -7
  9. package/dist/column-types.mjs.map +1 -1
  10. package/dist/{constants-Co5golCK.mjs → constants-DX-00vYk.mjs} +2 -2
  11. package/dist/{constants-Co5golCK.mjs.map → constants-DX-00vYk.mjs.map} +1 -1
  12. package/dist/control.d.mts.map +1 -1
  13. package/dist/control.mjs +163 -30
  14. package/dist/control.mjs.map +1 -1
  15. package/dist/descriptor-meta-DEgJjLLi.mjs +178 -0
  16. package/dist/descriptor-meta-DEgJjLLi.mjs.map +1 -0
  17. package/dist/operation-types-Bd-jkNN3.d.mts +38 -0
  18. package/dist/operation-types-Bd-jkNN3.d.mts.map +1 -0
  19. package/dist/operation-types.d.mts +2 -76
  20. package/dist/operation-types.mjs +1 -1
  21. package/dist/pack.d.mts +3 -10
  22. package/dist/pack.d.mts.map +1 -1
  23. package/dist/pack.mjs +2 -3
  24. package/dist/runtime.d.mts +10 -1
  25. package/dist/runtime.d.mts.map +1 -1
  26. package/dist/runtime.mjs +6 -25
  27. package/dist/runtime.mjs.map +1 -1
  28. package/package.json +32 -17
  29. package/src/contract.d.ts +91 -0
  30. package/src/contract.json +40 -0
  31. package/src/contract.ts +67 -0
  32. package/src/core/codecs.ts +127 -59
  33. package/src/core/contract-space-constants.ts +30 -0
  34. package/src/core/descriptor-meta.ts +40 -36
  35. package/src/core/registry.ts +11 -0
  36. package/src/exports/column-types.ts +3 -6
  37. package/src/exports/control.ts +56 -35
  38. package/src/exports/operation-types.ts +1 -1
  39. package/src/exports/runtime.ts +11 -41
  40. package/src/types/operation-types.ts +19 -36
  41. package/dist/codec-types-BifaP625.d.mts +0 -27
  42. package/dist/codec-types-BifaP625.d.mts.map +0 -1
  43. package/dist/descriptor-meta-BQbvJJxu.mjs +0 -148
  44. package/dist/descriptor-meta-BQbvJJxu.mjs.map +0 -1
  45. package/dist/operation-types.d.mts.map +0 -1
@@ -0,0 +1,40 @@
1
+ {
2
+ "schemaVersion": "1",
3
+ "targetFamily": "sql",
4
+ "target": "postgres",
5
+ "profileHash": "sha256:1a8dbe044289f30a1de958fe800cc5a8378b285d2e126a8c44b58864bac2c18e",
6
+ "roots": {},
7
+ "models": {},
8
+ "storage": {
9
+ "storageHash": "sha256:382dae5bb1548e62cbc449530ea08a9ce0a0dbb280401e9588642223f33783ae",
10
+ "tables": {},
11
+ "types": {
12
+ "vector": {
13
+ "codecId": "pg/vector@1",
14
+ "nativeType": "vector",
15
+ "typeParams": {}
16
+ }
17
+ }
18
+ },
19
+ "capabilities": {
20
+ "postgres": {
21
+ "jsonAgg": true,
22
+ "lateral": true,
23
+ "limit": true,
24
+ "orderBy": true,
25
+ "returning": true
26
+ },
27
+ "sql": {
28
+ "defaultInInsert": true,
29
+ "enums": true,
30
+ "returning": true
31
+ }
32
+ },
33
+ "extensionPacks": {},
34
+ "meta": {},
35
+ "_generated": {
36
+ "warning": "⚠️ GENERATED FILE - DO NOT EDIT",
37
+ "message": "This file is automatically generated by \"prisma-next contract emit\".",
38
+ "regenerate": "To regenerate, run: prisma-next contract emit"
39
+ }
40
+ }
@@ -0,0 +1,67 @@
1
+ /**
2
+ * TS contract source for the `extension-pgvector` package.
3
+ *
4
+ * Authored against the contract-space package layout convention. The
5
+ * same emit pipeline application authors use is applied here:
6
+ *
7
+ * `prisma-next contract emit` → `<package>/src/contract.{json,d.ts}`
8
+ * `prisma-next migration plan` → `<package>/migrations/<dirName>/`
9
+ *
10
+ * The descriptor at `src/exports/control.ts` then wires the emitted
11
+ * JSON artefacts via JSON-import declarations.
12
+ *
13
+ * ## IR coverage
14
+ *
15
+ * pgvector ships **no tables** of its own. The single object the
16
+ * extension contributes to the contract IR is the parameterised native
17
+ * type `vector(N)`, registered under `storage.types`. Per-column
18
+ * instances on the user's side carry concrete `typeParams.length`
19
+ * (e.g. `vector(1536)`); the registration here declares the
20
+ * parameterised shape so the verifier sees `vector` as part of
21
+ * pgvector's space contribution and so the pinned `contract.json` on
22
+ * disk is materially distinct from an empty space.
23
+ *
24
+ * Unlike CipherStash's deferred typed objects (composite types /
25
+ * domains / enums — IR vocabulary deferral, see
26
+ * `packages/3-extensions/cipherstash/src/contract.prisma`),
27
+ * pgvector's `vector` IS representable in today's IR via
28
+ * {@link StorageTypeInstance}.
29
+ *
30
+ * ## Why TS, not PSL
31
+ *
32
+ * The contract-space package layout convention prefers PSL
33
+ * (`src/contract.prisma`). pgvector is the narrow exception called out
34
+ * in the convention: PSL's `types {}` block instantiates parameterised
35
+ * types at app authoring time (`Vector1536 = pgvector.Vector(1536)`)
36
+ * but has no surface for an extension to register the parameterised
37
+ * BASE type itself (the `storage.types.vector` entry with empty
38
+ * `typeParams` shown below). Until PSL grows that surface, this
39
+ * extension keeps its contract source in TS.
40
+ *
41
+ * @see docs/architecture docs/adrs/ADR 212 - Contract spaces.md
42
+ */
43
+
44
+ import sqlFamily from '@prisma-next/family-sql/pack';
45
+ import { defineContract } from '@prisma-next/sql-contract-ts/contract-builder';
46
+ import postgresPack from '@prisma-next/target-postgres/pack';
47
+ import { VECTOR_CODEC_ID } from './core/constants';
48
+ import { PGVECTOR_NATIVE_TYPE } from './core/contract-space-constants';
49
+
50
+ export const contract = defineContract(
51
+ {
52
+ family: sqlFamily,
53
+ target: postgresPack,
54
+ },
55
+ () => ({
56
+ types: {
57
+ [PGVECTOR_NATIVE_TYPE]: {
58
+ codecId: VECTOR_CODEC_ID,
59
+ nativeType: PGVECTOR_NATIVE_TYPE,
60
+ typeParams: {},
61
+ },
62
+ },
63
+ models: {},
64
+ }),
65
+ );
66
+
67
+ export default contract;
@@ -1,77 +1,145 @@
1
1
  /**
2
- * Vector codec implementation for pgvector extension.
2
+ * pgvector extension codec.
3
3
  *
4
- * Provides encoding/decoding for the `vector` PostgreSQL type.
5
- * Wire format is a string like `[1,2,3]` (PostgreSQL vector text format).
4
+ * Mirrors the patterns in `postgres/codecs-class.ts` and `sqlite/codecs-class.ts` for the single `pg/vector@1` codec. Three artifacts:
5
+ *
6
+ * 1. `PgVectorCodec` extends {@link CodecImpl} with the runtime encode/decode/encodeJson/decodeJson conversions inline. Conversions are simple enough (PostgreSQL `[1,2,3]` text format) that no shared helper module is warranted; the class body is the source of truth.
7
+ * 2. `PgVectorDescriptor` extends {@link CodecDescriptorImpl} with the codec id, traits, target types, params schema (`{ length: number }`, validated against {@link VECTOR_MAX_DIM}), `meta` (postgres `nativeType: 'vector'`), and the emit-path `renderOutputType` producing `Vector<${length}>`.
8
+ * 3. `pgVectorColumn(length)` per-codec column helper invoking `descriptor.factory({ length })` directly + passing the bare `nativeType: 'vector'`. The family-layer {@link expandNativeType} hook renders the parameterized form (`vector(1536)`) at emit/verify time from `nativeType` + `typeParams`.
9
+ *
10
+ * `length` threads into the runtime codec via the constructor so encode/decode/encodeJson/decodeJson enforce the declared dimension at every ingress path. Without this, `vector(3)` and `vector(1536)` would produce codecs with identical behaviour and a dimension-mismatched value would round-trip undetected.
6
11
  */
7
12
 
8
- import { codec, defineCodecs } from '@prisma-next/sql-relational-core/ast';
9
-
10
- const pgVectorCodec = codec({
11
- typeId: 'pg/vector@1',
12
- targetTypes: ['vector'],
13
- traits: ['equality'],
14
- renderOutputType: (typeParams) => {
15
- const length = typeParams['length'];
16
- if (length === undefined) return undefined;
17
- if (typeof length !== 'number' || !Number.isFinite(length) || !Number.isInteger(length)) {
18
- throw new Error(
19
- `renderOutputType: expected positive integer "length" in typeParams for Vector, got ${String(length)}`,
20
- );
21
- }
22
- return `Vector<${length}>`;
23
- },
24
- encode: (value: number[]): string => {
25
- // Validate that value is an array of numbers
13
+ import type { JsonValue } from '@prisma-next/contract/types';
14
+ import {
15
+ type AnyCodecDescriptor,
16
+ type CodecCallContext,
17
+ CodecDescriptorImpl,
18
+ CodecImpl,
19
+ type CodecInstanceContext,
20
+ type ColumnHelperFor,
21
+ type ColumnHelperForStrict,
22
+ column,
23
+ } from '@prisma-next/framework-components/codec';
24
+ import type { ExtractCodecTypes } from '@prisma-next/sql-relational-core/ast';
25
+ import type { StandardSchemaV1 } from '@standard-schema/spec';
26
+ import { type as arktype } from 'arktype';
27
+ import { VECTOR_CODEC_ID, VECTOR_MAX_DIM } from './constants';
28
+
29
+ type VectorParams = { readonly length: number };
30
+
31
+ const vectorParamsSchema = arktype({
32
+ length: 'number',
33
+ }).narrow((params, ctx) => {
34
+ const { length } = params;
35
+ if (!Number.isInteger(length)) {
36
+ return ctx.mustBe('an integer');
37
+ }
38
+ if (length < 1 || length > VECTOR_MAX_DIM) {
39
+ return ctx.mustBe(`in the range [1, ${VECTOR_MAX_DIM}]`);
40
+ }
41
+ return true;
42
+ }) satisfies StandardSchemaV1<VectorParams>;
43
+
44
+ const PG_VECTOR_META = { db: { sql: { postgres: { nativeType: 'vector' } } } } as const;
45
+
46
+ export class PgVectorCodec extends CodecImpl<
47
+ typeof VECTOR_CODEC_ID,
48
+ readonly ['equality'],
49
+ string,
50
+ number[]
51
+ > {
52
+ readonly length: number | undefined;
53
+
54
+ constructor(descriptor: AnyCodecDescriptor, length: number | undefined) {
55
+ super(descriptor);
56
+ this.length = length;
57
+ }
58
+
59
+ assertVector(value: unknown): asserts value is number[] {
26
60
  if (!Array.isArray(value)) {
27
61
  throw new Error('Vector value must be an array of numbers');
28
62
  }
29
63
  if (!value.every((v) => typeof v === 'number')) {
30
64
  throw new Error('Vector value must contain only numbers');
31
65
  }
32
- // Format as PostgreSQL vector text format: [1,2,3]
33
- // PostgreSQL's pg library requires the vector format string
66
+ if (this.length !== undefined && value.length !== this.length) {
67
+ throw new Error(`Vector length mismatch: expected ${this.length}, got ${value.length}`);
68
+ }
69
+ }
70
+
71
+ async encode(value: number[], _ctx: CodecCallContext): Promise<string> {
72
+ this.assertVector(value);
34
73
  return `[${value.join(',')}]`;
35
- },
36
- decode: (wire: string): number[] => {
37
- // Handle string format from PostgreSQL: [1,2,3]
74
+ }
75
+
76
+ async decode(wire: string, _ctx: CodecCallContext): Promise<number[]> {
38
77
  if (typeof wire !== 'string') {
39
78
  throw new Error('Vector wire value must be a string');
40
79
  }
41
- // Parse PostgreSQL vector format: [1,2,3]
42
80
  if (!wire.startsWith('[') || !wire.endsWith(']')) {
43
81
  throw new Error(`Invalid vector format: expected "[...]", got "${wire}"`);
44
82
  }
45
83
  const content = wire.slice(1, -1).trim();
46
- if (content === '') {
47
- return [];
48
- }
49
- const values = content.split(',').map((v) => {
50
- const num = Number.parseFloat(v.trim());
51
- if (Number.isNaN(num)) {
52
- throw new Error(`Invalid vector value: "${v}" is not a number`);
53
- }
54
- return num;
55
- });
56
- return values;
57
- },
58
- meta: {
59
- db: {
60
- sql: {
61
- postgres: {
62
- nativeType: 'vector',
63
- },
64
- },
65
- },
66
- },
67
- });
68
-
69
- // Build codec definitions using the builder DSL
70
- const codecs = defineCodecs().add('vector', pgVectorCodec);
71
-
72
- // Export derived structures directly from codecs builder
73
- export const codecDefinitions = codecs.codecDefinitions;
74
- export const dataTypes = codecs.dataTypes;
75
-
76
- // Export types derived from codecs builder
77
- export type CodecTypes = typeof codecs.CodecTypes;
84
+ const parsed =
85
+ content === ''
86
+ ? []
87
+ : content.split(',').map((v) => {
88
+ const num = Number.parseFloat(v.trim());
89
+ if (Number.isNaN(num)) {
90
+ throw new Error(`Invalid vector value: "${v}" is not a number`);
91
+ }
92
+ return num;
93
+ });
94
+ this.assertVector(parsed);
95
+ return parsed;
96
+ }
97
+
98
+ encodeJson(value: number[]): JsonValue {
99
+ this.assertVector(value);
100
+ return value;
101
+ }
102
+
103
+ decodeJson(json: JsonValue): number[] {
104
+ this.assertVector(json);
105
+ return json;
106
+ }
107
+ }
108
+
109
+ export class PgVectorDescriptor extends CodecDescriptorImpl<VectorParams> {
110
+ override readonly codecId = VECTOR_CODEC_ID;
111
+ override readonly traits = ['equality'] as const;
112
+ override readonly targetTypes = ['vector'] as const;
113
+ override readonly meta = PG_VECTOR_META;
114
+ override readonly paramsSchema: StandardSchemaV1<VectorParams> = vectorParamsSchema;
115
+ override renderOutputType(params: VectorParams): string {
116
+ return `Vector<${params.length}>`;
117
+ }
118
+ /**
119
+ * The runtime calls `factory(undefined)(ctx)` to materialize a representative codec for parameterized descriptors that ship a no-params column variant (here, `vectorColumn` vs `vector(N)`). The runtime cast widens `params` to `unknown`, so guarding with an optional read keeps the typed call site (`factory({ length })`) strict while still producing a length-agnostic codec for representative use. Encode/decode for an undimensioned column run through this representative; the wire format `[v1,v2,...]` is dimension-independent.
120
+ */
121
+ override factory(params: VectorParams): (ctx: CodecInstanceContext) => PgVectorCodec {
122
+ return () => new PgVectorCodec(this, (params as VectorParams | undefined)?.length);
123
+ }
124
+ }
125
+
126
+ export const pgVectorDescriptor = new PgVectorDescriptor();
127
+
128
+ /**
129
+ * Per-codec column helper for `pg/vector@1`. Generic over `N extends number` so the column site preserves the dimension literal in `typeParams` (e.g. `pgVectorColumn(1536)` packs `typeParams: { length: 1536 }`).
130
+ *
131
+ * Passes the bare `nativeType: 'vector'`; the family-layer `expandNativeType` hook renders the parameterized form (`vector(1536)`) at emit/verify time from `nativeType` + `typeParams`.
132
+ */
133
+ export const pgVectorColumn = <N extends number>(length: N) =>
134
+ column(pgVectorDescriptor.factory({ length }), pgVectorDescriptor.codecId, { length }, 'vector');
135
+
136
+ pgVectorColumn satisfies ColumnHelperFor<PgVectorDescriptor>;
137
+ pgVectorColumn satisfies ColumnHelperForStrict<PgVectorDescriptor>;
138
+
139
+ const codecDescriptorMap = {
140
+ vector: pgVectorDescriptor,
141
+ } as const;
142
+
143
+ export type CodecTypes = ExtractCodecTypes<typeof codecDescriptorMap>;
144
+
145
+ export const codecDescriptors: readonly AnyCodecDescriptor[] = Object.values(codecDescriptorMap);
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Static names and identifiers used across pgvector's contract space.
3
+ *
4
+ * Centralised here so the contract IR (`./contract`), the baseline
5
+ * migration ops (`./migrations`), the head ref, and the descriptor
6
+ * (`../exports/control`) all reference the same values without typos.
7
+ *
8
+ * The space identifier `'pgvector'` is what the framework writes to
9
+ * `migrations/` in the user's repo and what the marker table's
10
+ * `space` column carries for pgvector-owned rows.
11
+ *
12
+ * The `pgvector:*` invariantId namespace is locked here — once
13
+ * published, an invariantId is immutable so downstream consumers can
14
+ * reference it by literal string match.
15
+ */
16
+
17
+ export const PGVECTOR_SPACE_ID = 'pgvector' as const;
18
+
19
+ export const PGVECTOR_NATIVE_TYPE = 'vector' as const;
20
+
21
+ export const PGVECTOR_BASELINE_MIGRATION_NAME = '20260601T0000_install_vector_extension' as const;
22
+
23
+ /**
24
+ * `pgvector:*` invariantIds emitted by the baseline migration. Each id,
25
+ * once published, is immutable: downstream consumers (other extensions,
26
+ * the marker table) reference them by literal string match.
27
+ */
28
+ export const PGVECTOR_INVARIANTS = {
29
+ installVector: 'pgvector:install-vector-v1',
30
+ } as const;
@@ -1,38 +1,49 @@
1
- import type { SqlOperationDescriptor } from '@prisma-next/sql-operations';
1
+ import { buildOperation, refsOf, toExpr } from '@prisma-next/sql-relational-core/expression';
2
2
  import type { CodecTypes } from '../types/codec-types';
3
+ import type { QueryOperationTypes } from '../types/operation-types';
3
4
  import { pgvectorAuthoringTypes } from './authoring';
4
- import { codecDefinitions } from './codecs';
5
+ import { pgvectorCodecRegistry } from './registry';
5
6
 
6
7
  const pgvectorTypeId = 'pg/vector@1' as const;
7
8
 
8
- export const pgvectorQueryOperations: readonly SqlOperationDescriptor[] = [
9
- {
10
- method: 'cosineDistance',
11
- args: [
12
- { codecId: pgvectorTypeId, nullable: false },
13
- { codecId: pgvectorTypeId, nullable: false },
14
- ],
15
- returns: { codecId: 'pg/float8@1', nullable: false },
16
- lowering: {
17
- targetFamily: 'sql',
18
- strategy: 'function',
19
- template: '{{self}} <=> {{arg0}}',
9
+ type CodecTypesBase = Record<string, { readonly input: unknown; readonly output: unknown }>;
10
+
11
+ export function pgvectorQueryOperations<CT extends CodecTypesBase>(): QueryOperationTypes<CT> {
12
+ return {
13
+ cosineDistance: {
14
+ self: { codecId: pgvectorTypeId },
15
+ impl: (self, other) => {
16
+ const selfRefs = refsOf(self);
17
+ return buildOperation({
18
+ method: 'cosineDistance',
19
+ args: [toExpr(self, pgvectorTypeId, selfRefs), toExpr(other, pgvectorTypeId, selfRefs)],
20
+ returns: { codecId: 'pg/float8@1', nullable: false },
21
+ lowering: {
22
+ targetFamily: 'sql',
23
+ strategy: 'function',
24
+ template: '{{self}} <=> {{arg0}}',
25
+ },
26
+ });
27
+ },
20
28
  },
21
- },
22
- {
23
- method: 'cosineSimilarity',
24
- args: [
25
- { codecId: pgvectorTypeId, nullable: false },
26
- { codecId: pgvectorTypeId, nullable: false },
27
- ],
28
- returns: { codecId: 'pg/float8@1', nullable: false },
29
- lowering: {
30
- targetFamily: 'sql',
31
- strategy: 'function',
32
- template: '1 - ({{self}} <=> {{arg0}})',
29
+ cosineSimilarity: {
30
+ self: { codecId: pgvectorTypeId },
31
+ impl: (self, other) => {
32
+ const selfRefs = refsOf(self);
33
+ return buildOperation({
34
+ method: 'cosineSimilarity',
35
+ args: [toExpr(self, pgvectorTypeId, selfRefs), toExpr(other, pgvectorTypeId, selfRefs)],
36
+ returns: { codecId: 'pg/float8@1', nullable: false },
37
+ lowering: {
38
+ targetFamily: 'sql',
39
+ strategy: 'function',
40
+ template: '1 - ({{self}} <=> {{arg0}})',
41
+ },
42
+ });
43
+ },
33
44
  },
34
- },
35
- ];
45
+ };
46
+ }
36
47
 
37
48
  const pgvectorPackMetaBase = {
38
49
  kind: 'extension',
@@ -50,7 +61,7 @@ const pgvectorPackMetaBase = {
50
61
  },
51
62
  types: {
52
63
  codecTypes: {
53
- codecInstances: Object.values(codecDefinitions).map((def) => def.codec),
64
+ codecDescriptors: Array.from(pgvectorCodecRegistry.values()),
54
65
  import: {
55
66
  package: '@prisma-next/extension-pgvector/codec-types',
56
67
  named: 'CodecTypes',
@@ -64,13 +75,6 @@ const pgvectorPackMetaBase = {
64
75
  },
65
76
  ],
66
77
  },
67
- operationTypes: {
68
- import: {
69
- package: '@prisma-next/extension-pgvector/operation-types',
70
- named: 'OperationTypes',
71
- alias: 'PgVectorOperationTypes',
72
- },
73
- },
74
78
  queryOperationTypes: {
75
79
  import: {
76
80
  package: '@prisma-next/extension-pgvector/operation-types',
@@ -0,0 +1,11 @@
1
+ import { buildCodecDescriptorRegistry } from '@prisma-next/sql-relational-core/codec-descriptor-registry';
2
+ import type { CodecDescriptorRegistry } from '@prisma-next/sql-relational-core/query-lane-context';
3
+ import { codecDescriptors } from './codecs';
4
+
5
+ /**
6
+ * Registry of every codec descriptor shipped by `@prisma-next/extension-pgvector`.
7
+ *
8
+ * 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.
9
+ */
10
+ export const pgvectorCodecRegistry: CodecDescriptorRegistry =
11
+ buildCodecDescriptorRegistry(codecDescriptors);
@@ -1,16 +1,14 @@
1
1
  /**
2
2
  * Column type descriptors for pgvector extension.
3
3
  *
4
- * These descriptors provide both codecId and nativeType for use in contract authoring.
5
- * They are derived from the same source of truth as codec definitions and manifests.
4
+ * 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.
6
5
  */
7
6
 
8
- import type { ColumnTypeDescriptor } from '@prisma-next/contract-authoring';
7
+ import type { ColumnTypeDescriptor } from '@prisma-next/framework-components/codec';
9
8
  import { VECTOR_CODEC_ID, VECTOR_MAX_DIM } from '../core/constants';
10
9
 
11
10
  /**
12
- * Static vector column descriptor without dimension.
13
- * Use `vector(N)` for dimensioned vectors that produce `vector(N)` DDL.
11
+ * Static vector column descriptor without dimension. Use `vector(N)` for dimensioned vectors that produce `vector(N)` DDL.
14
12
  */
15
13
  export const vectorColumn = {
16
14
  codecId: VECTOR_CODEC_ID,
@@ -25,7 +23,6 @@ export const vectorColumn = {
25
23
  * .column('embedding', { type: vector(1536), nullable: false })
26
24
  * // Produces: nativeType: 'vector', typeParams: { length: 1536 }
27
25
  * ```
28
- *
29
26
  * @param length - The dimension of the vector (e.g., 1536 for OpenAI embeddings)
30
27
  * @returns A column type descriptor with `typeParams.length` set
31
28
  * @throws {RangeError} If length is not an integer in the range [1, VECTOR_MAX_DIM]
@@ -1,11 +1,55 @@
1
+ /**
2
+ * Control-plane descriptor for the pgvector extension.
3
+ *
4
+ * **Contract-space package layout.** The extension's contract
5
+ * + migrations are emitted by the same pipeline application authors use:
6
+ *
7
+ * `prisma-next contract emit` → `<package>/src/contract.{json,d.ts}`
8
+ * `prisma-next migration plan` → `<package>/migrations/<dir>/...`
9
+ *
10
+ * The descriptor wires those JSON artefacts via JSON-import declarations
11
+ * so they flow through the consuming application's module resolver
12
+ * without filesystem assumptions, and synthesises the canonical
13
+ * {@link import('@prisma-next/framework-components/control').MigrationPackage}
14
+ * shape for the framework's runner / verifier to consume. Readers in
15
+ * `@prisma-next/migration-tools` add `dirPath` when loading from disk
16
+ * (`OnDiskMigrationPackage`); descriptor-bundled packages do not need
17
+ * it because the framework reads them directly from the descriptor.
18
+ *
19
+ * Wired surfaces:
20
+ *
21
+ * - `contractSpace.{contractJson,migrations,headRef}` — sourced from
22
+ * the on-disk artefacts emitted by `build:contract-space`.
23
+ * - `types.codecTypes.controlPlaneHooks[PGVECTOR_CODEC_ID]` — codec
24
+ * control hooks (`expandNativeType`, `resolveIdentityValue`) the
25
+ * SQL planner extracts via `extractCodecControlHooks` and uses to
26
+ * render `vector(N)` column types and the canonical zero-vector
27
+ * identity literal.
28
+ *
29
+ * @see docs/architecture docs/adrs/ADR 212 - Contract spaces.md
30
+ * (contract-space package layout convention).
31
+ */
32
+
33
+ import type { Contract } from '@prisma-next/contract/types';
1
34
  import type {
2
35
  CodecControlHooks,
3
- ComponentDatabaseDependencies,
4
36
  SqlControlExtensionDescriptor,
5
37
  } from '@prisma-next/family-sql/control';
38
+ import { contractSpaceFromJson } from '@prisma-next/migration-tools/spaces';
39
+ import type { SqlStorage } from '@prisma-next/sql-contract/types';
40
+ import baselineMetadata from '../../migrations/20260601T0000_install_vector_extension/migration.json' with {
41
+ type: 'json',
42
+ };
43
+ import baselineOps from '../../migrations/20260601T0000_install_vector_extension/ops.json' with {
44
+ type: 'json',
45
+ };
46
+ import headRef from '../../migrations/refs/head.json' with { type: 'json' };
47
+ import contractJson from '../contract.json' with { type: 'json' };
48
+ import { PGVECTOR_SPACE_ID } from '../core/contract-space-constants';
6
49
  import { pgvectorPackMeta, pgvectorQueryOperations } from '../core/descriptor-meta';
7
50
 
8
51
  const PGVECTOR_CODEC_ID = 'pg/vector@1' as const;
52
+ const BASELINE_DIR_NAME = '20260601T0000_install_vector_extension';
9
53
 
10
54
  function buildVectorIdentityValue(typeParams: Record<string, unknown> | undefined): string | null {
11
55
  const length = typeParams?.['length'];
@@ -28,44 +72,22 @@ const vectorControlPlaneHooks: CodecControlHooks = {
28
72
  resolveIdentityValue: ({ typeParams }) => buildVectorIdentityValue(typeParams),
29
73
  };
30
74
 
31
- const pgvectorDatabaseDependencies: ComponentDatabaseDependencies<unknown> = {
32
- init: [
75
+ const pgvectorContractSpace = contractSpaceFromJson<Contract<SqlStorage>>({
76
+ contractJson,
77
+ migrations: [
33
78
  {
34
- id: 'postgres.extension.vector',
35
- label: 'Enable vector extension',
36
- install: [
37
- {
38
- id: 'extension.vector',
39
- label: 'Enable extension "vector"',
40
- summary: 'Ensures the vector extension is available for pgvector operations',
41
- operationClass: 'additive',
42
- target: { id: 'postgres' },
43
- precheck: [
44
- {
45
- description: 'verify extension "vector" is not already enabled',
46
- sql: "SELECT NOT EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'vector')",
47
- },
48
- ],
49
- execute: [
50
- {
51
- description: 'create extension "vector"',
52
- sql: 'CREATE EXTENSION IF NOT EXISTS vector',
53
- },
54
- ],
55
- postcheck: [
56
- {
57
- description: 'confirm extension "vector" is enabled',
58
- sql: "SELECT EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'vector')",
59
- },
60
- ],
61
- },
62
- ],
79
+ dirName: BASELINE_DIR_NAME,
80
+ metadata: baselineMetadata,
81
+ ops: baselineOps,
63
82
  },
64
83
  ],
65
- };
84
+ headRef,
85
+ });
66
86
 
67
87
  const pgvectorExtensionDescriptor: SqlControlExtensionDescriptor<'postgres'> = {
68
88
  ...pgvectorPackMeta,
89
+ id: PGVECTOR_SPACE_ID,
90
+ contractSpace: pgvectorContractSpace,
69
91
  types: {
70
92
  ...pgvectorPackMeta.types,
71
93
  codecTypes: {
@@ -75,8 +97,7 @@ const pgvectorExtensionDescriptor: SqlControlExtensionDescriptor<'postgres'> = {
75
97
  },
76
98
  },
77
99
  },
78
- queryOperations: () => pgvectorQueryOperations,
79
- databaseDependencies: pgvectorDatabaseDependencies,
100
+ queryOperations: () => pgvectorQueryOperations(),
80
101
  create: () => ({
81
102
  familyId: 'sql' as const,
82
103
  targetId: 'postgres' as const,
@@ -4,4 +4,4 @@
4
4
  * Re-export from types module for public API.
5
5
  */
6
6
 
7
- export type { OperationTypes, QueryOperationTypes } from '../types/operation-types';
7
+ export type { QueryOperationTypes } from '../types/operation-types';