@nicia-ai/typegraph 0.28.0 → 0.29.0

package/dist/index.js

@@ -1,23 +1,26 @@
-import { quoteIdentifier, EMPTY_REQUIRED_COLUMNS, addRequiredColumn, markSelectiveFieldAsRequired, markFieldRefAsRequired, NODE_COLUMNS, shouldProjectColumn, mapSelectiveSystemFieldToColumn, isIdFieldRef, isAggregateExpr, EDGE_COLUMNS } from './chunk-3EUKJEQ3.js';
-import { META_EDGE_BRAND, loadAndMergeGraphExtensionDocument, ensureSchema, loadAndVerifyGraph, mergeGraphExtension, commitNewSchemaVersion, applyDeprecatedKinds, loadActiveSchemaWithBootstrap, parseSerializedSchema, computeClosuresFromOntology, createEmptyClosures, KindRegistry, extensionKindNames, serializeSchemaProperties, buildGraphExtensionOntologyKeySet, compileTimeOntologyKey, getTypeName, validateNodeProps, validateEdgeProps } from './chunk-X53YKGHR.js';
-export { broader, core, defineEdge, defineNode, differentFrom, disjointWith, equivalentTo, hasPart, implies, inverseOf, isMetaEdge, narrower, partOf, relatedTo, sameAs, subClassOf } from './chunk-X53YKGHR.js';
-import { nowIso, isKnownKind, validateOptionalIsoDate, getNodeKinds, getEdgeKinds } from './chunk-OYLF3IC7.js';
-export { defineGraph, getEdgeKinds, getNodeKinds, isEdgeType, isEdgeTypeWithEndpoints, isGraphDef, isNodeType } from './chunk-OYLF3IC7.js';
-export { defineGraphExtension } from './chunk-E5ROA3MN.js';
-import { IncompatibleChangeError, filterReservedKeys, RESERVED_NODE_KEYS, RESERVED_EDGE_KEYS, RemoveCompileTimeKindError, KindHasReferentsError, validateProjectionField } from './chunk-TSGBRPNE.js';
-export { CURRENT_GRAPH_EXTENSION_VERSION, GraphExtensionError, GraphExtensionUnresolvedEndpointError, GraphExtensionValidationError, GraphExtensionVersionUnsupportedError, IncompatibleChangeError, KindCollisionError, KindHasReferentsError, LEGACY_GRAPH_EXTENSION_VERSION, RemoveCompileTimeKindError, validateGraphExtension } from './chunk-TSGBRPNE.js';
-import { runOptionallyInTransaction } from './chunk-PCHTTG42.js';
-import { canonicalEqual, sortedReplacer } from './chunk-5H3BAMTB.js';
-import { getDialect, generateIndexDDL } from './chunk-ZTREJOGB.js';
-export { andWhere, fts5Strategy, notWhere, orWhere, tsvectorStrategy } from './chunk-ZTREJOGB.js';
-import { MAX_PG_IDENTIFIER_LENGTH, DEFAULT_PAGINATION_LIMIT, DEFAULT_STREAM_BATCH_SIZE, NODE_META_KEYS, EDGE_META_KEYS, SQLITE_PATH_DELIMITER, PG_ARRAY_START, PG_ARRAY_END, PG_PATH_ELEMENT_SEPARATOR, fnv1aBase36, sha256Hex } from './chunk-EJCDOA37.js';
-export { defineEdgeIndex, defineNodeIndex } from './chunk-EJCDOA37.js';
-import { createSchemaIntrospector, resolveFieldTypeInfoAtJsonPointer, getSearchableMetadata, DEFAULT_SEARCHABLE_LANGUAGE } from './chunk-OOS2RKRH.js';
-export { DEFAULT_SEARCHABLE_LANGUAGE, getSearchableMetadata, isSearchableSchema, searchable } from './chunk-OOS2RKRH.js';
-import { getEmbeddingDimensions, isEmbeddingSchema } from './chunk-WVQXAFP3.js';
-export { embedding, getEmbeddingDimensions, isEmbeddingSchema } from './chunk-WVQXAFP3.js';
-import { ConfigurationError, UnsupportedPredicateError, ValidationError, KindNotFoundError, EndpointError, EagerMaterializationError, CompilerInvariantError, DatabaseOperationError, EdgeNotFoundError, NodeConstraintNotFoundError, RestrictedDeleteError, NodeNotFoundError, EndpointNotFoundError, UniquenessError, CardinalityError, DisjointError } from './chunk-U5ROKVRF.js';
-export { BackendDisposedError, CardinalityError, CompilerInvariantError, ConfigurationError, DatabaseOperationError, DisjointError, EagerMaterializationError, EdgeNotFoundError, EndpointError, EndpointNotFoundError, KindNotFoundError, MigrationError, NodeConstraintNotFoundError, NodeNotFoundError, RestrictedDeleteError, SchemaContentConflictError, SchemaMismatchError, StaleVersionError, StoreNotInitializedError, TypeGraphError, UniquenessError, UnsupportedPredicateError, ValidationError, VersionConflictError, getErrorSuggestion, isConstraintError, isSystemError, isTypeGraphError, isUserRecoverable } from './chunk-U5ROKVRF.js';
+export { libsqlVectorStrategy } from './chunk-CUZGBWFT.js';
+import { quoteIdentifier, EMPTY_REQUIRED_COLUMNS, addRequiredColumn, markSelectiveFieldAsRequired, markFieldRefAsRequired, NODE_COLUMNS, shouldProjectColumn, mapSelectiveSystemFieldToColumn, isIdFieldRef, isAggregateExpr, EDGE_COLUMNS } from './chunk-IE2TPFBT.js';
+export { pgvectorStrategy } from './chunk-IE2TPFBT.js';
+import { META_EDGE_BRAND, loadAndMergeGraphExtensionDocument, ensureSchema, loadAndVerifyGraph, mergeGraphExtension, commitNewSchemaVersion, applyDeprecatedKinds, loadActiveSchemaWithBootstrap, parseSerializedSchema, computeClosuresFromOntology, createEmptyClosures, KindRegistry, extensionKindNames, serializeSchemaProperties, buildGraphExtensionOntologyKeySet, compileTimeOntologyKey, getTypeName, validateNodeProps, validateEdgeProps } from './chunk-MRMD7S7E.js';
+export { broader, core, defineEdge, defineNode, differentFrom, disjointWith, equivalentTo, hasPart, implies, inverseOf, isMetaEdge, narrower, partOf, relatedTo, sameAs, subClassOf } from './chunk-MRMD7S7E.js';
+import { nowIso, isKnownKind, validateOptionalIsoDate, getNodeKinds, getEdgeKinds } from './chunk-Z36W5WUM.js';
+export { defineGraph, getEdgeKinds, getNodeKinds, isEdgeType, isEdgeTypeWithEndpoints, isGraphDef, isNodeType } from './chunk-Z36W5WUM.js';
+export { defineGraphExtension } from './chunk-BMDF2S7S.js';
+import { IncompatibleChangeError, filterReservedKeys, RESERVED_NODE_KEYS, RESERVED_EDGE_KEYS, RemoveCompileTimeKindError, KindHasReferentsError, validateProjectionField } from './chunk-SFNUHFON.js';
+export { CURRENT_GRAPH_EXTENSION_VERSION, GraphExtensionError, GraphExtensionUnresolvedEndpointError, GraphExtensionValidationError, GraphExtensionVersionUnsupportedError, IncompatibleChangeError, KindCollisionError, KindHasReferentsError, LEGACY_GRAPH_EXTENSION_VERSION, RemoveCompileTimeKindError, computeTransitiveClosure, invertClosure, isReachable, validateGraphExtension } from './chunk-SFNUHFON.js';
+export { sqliteVecStrategy } from './chunk-GPUNAJFH.js';
+import { LEGACY_EMBEDDINGS_TABLE_NAME, runOptionallyInTransaction } from './chunk-HKN622O4.js';
+import { isMissingTableError, sortedReplacer, canonicalEqual } from './chunk-M6OC455F.js';
+import { quotedTableName, getDialect, assertVectorMinScore, generateIndexDDL, vectorScoreExpression, vectorMinScoreCondition } from './chunk-7KLVFWXR.js';
+export { andWhere, buildVectorCapabilities, fts5Strategy, notWhere, orWhere, tsvectorStrategy } from './chunk-7KLVFWXR.js';
+import { MAX_PG_IDENTIFIER_LENGTH, DEFAULT_PAGINATION_LIMIT, DEFAULT_STREAM_BATCH_SIZE, NODE_META_KEYS, EDGE_META_KEYS, sha256Hex, SQLITE_PATH_DELIMITER, PG_ARRAY_START, PG_ARRAY_END, PG_PATH_ELEMENT_SEPARATOR, fnv1aBase36 } from './chunk-OGUH56BB.js';
+export { defineEdgeIndex, defineNodeIndex } from './chunk-OGUH56BB.js';
+import { createSchemaIntrospector, resolveFieldTypeInfoAtJsonPointer, getSearchableMetadata, DEFAULT_SEARCHABLE_LANGUAGE } from './chunk-N3VVQDMA.js';
+export { DEFAULT_SEARCHABLE_LANGUAGE, getSearchableMetadata, isSearchableSchema, searchable } from './chunk-N3VVQDMA.js';
+import { DEFAULT_EMBEDDING_INDEX_TYPE, DEFAULT_EMBEDDING_METRIC, resolveEmbeddingFields } from './chunk-454I6GDF.js';
+export { embedding, getEmbeddingDimensions, isEmbeddingSchema } from './chunk-454I6GDF.js';
+import { ConfigurationError, EmbeddingDimensionChangedError, UnsupportedPredicateError, ValidationError, KindNotFoundError, EndpointError, EagerMaterializationError, CompilerInvariantError, DatabaseOperationError, EdgeNotFoundError, NodeConstraintNotFoundError, RestrictedDeleteError, NodeNotFoundError, EndpointNotFoundError, UniquenessError, CardinalityError, DisjointError } from './chunk-MB363HT5.js';
+export { BackendDisposedError, CardinalityError, CompilerInvariantError, ConfigurationError, DatabaseOperationError, DisjointError, EagerMaterializationError, EdgeNotFoundError, EmbeddingDimensionChangedError, EndpointError, EndpointNotFoundError, KindNotFoundError, MigrationError, NodeConstraintNotFoundError, NodeNotFoundError, RestrictedDeleteError, SchemaContentConflictError, SchemaMismatchError, StaleVersionError, StoreNotInitializedError, TypeGraphError, UniquenessError, UnsupportedPredicateError, ValidationError, VersionConflictError, getErrorSuggestion, isConstraintError, isSystemError, isTypeGraphError, isUserRecoverable } from './chunk-MB363HT5.js';
 import { jsonPointer, parseJsonPointer, normalizeJsonPointer, joinJsonPointers } from './chunk-NZ5PMBTG.js';
 export { MAX_JSON_POINTER_DEPTH, joinJsonPointers, jsonPointer, normalizeJsonPointer, parseJsonPointer } from './chunk-NZ5PMBTG.js';
 import { z } from 'zod';
@@ -67,6 +70,184 @@ function getExternalRefTable(schema) {
 function createExternalRef(table) {
   return (id) => ({ table, id });
 }
+var DEFAULT_BATCH_SIZE = 500;
+var DEFAULT_SLOT_METRIC = DEFAULT_EMBEDDING_METRIC;
+var DEFAULT_SLOT_INDEX_TYPE = DEFAULT_EMBEDDING_INDEX_TYPE;
+async function migrateLegacyEmbeddings(options) {
+  const {
+    backend,
+    graphId,
+    resolveSlotConfig,
+    batchSize = DEFAULT_BATCH_SIZE,
+    legacyTableName = LEGACY_EMBEDDINGS_TABLE_NAME
+  } = options;
+  if (backend.vectorStrategy === void 0 || backend.upsertEmbedding === void 0) {
+    throw new Error(
+      "migrateLegacyEmbeddings requires a backend wired with a vectorStrategy (the destination per-field storage). Pass the post-cutover backend."
+    );
+  }
+  if (!Number.isInteger(batchSize) || batchSize <= 0) {
+    throw new RangeError(
+      `batchSize must be a positive integer, got: ${batchSize}`
+    );
+  }
+  const upsertEmbedding = backend.upsertEmbedding;
+  const perField = {};
+  const skippedDimensionMismatch = {};
+  const skippedDecodeError = {};
+  let migrated = 0;
+  let cursor;
+  for (; ; ) {
+    let batch;
+    try {
+      batch = await readLegacyBatch(backend, {
+        legacyTableName,
+        graphId,
+        batchSize,
+        after: cursor
+      });
+    } catch (error) {
+      if (cursor === void 0 && isMissingTableError(error)) {
+        return {
+          migrated: 0,
+          perField: {},
+          skippedDimensionMismatch: {},
+          skippedDecodeError: {},
+          legacyTablePresent: false
+        };
+      }
+      throw error;
+    }
+    if (batch.length === 0) break;
+    for (const row of batch) {
+      const slotKey = `${row.node_kind}.${row.field_path}`;
+      let embedding2;
+      try {
+        embedding2 = decodeEmbeddingJson(row);
+      } catch {
+        skippedDecodeError[slotKey] = (skippedDecodeError[slotKey] ?? 0) + 1;
+        continue;
+      }
+      const config = resolveSlotConfig?.(row.node_kind, row.field_path);
+      try {
+        await upsertEmbedding({
+          graphId: row.graph_id,
+          nodeKind: row.node_kind,
+          nodeId: row.node_id,
+          fieldPath: row.field_path,
+          embedding: embedding2,
+          // The decoded length is the authoritative fixed dimension — the
+          // strategy provisions its column type (e.g. `F32_BLOB(N)`) from it.
+          dimensions: embedding2.length,
+          metric: config?.metric ?? DEFAULT_SLOT_METRIC,
+          indexType: config?.indexType ?? DEFAULT_SLOT_INDEX_TYPE
+        });
+      } catch (error) {
+        if (error instanceof EmbeddingDimensionChangedError) {
+          skippedDimensionMismatch[slotKey] = (skippedDimensionMismatch[slotKey] ?? 0) + 1;
+          continue;
+        }
+        throw error;
+      }
+      migrated += 1;
+      perField[slotKey] = (perField[slotKey] ?? 0) + 1;
+    }
+    if (batch.length < batchSize) break;
+    const last = batch.at(-1);
+    cursor = {
+      graphId: last.graph_id,
+      nodeKind: last.node_kind,
+      nodeId: last.node_id,
+      fieldPath: last.field_path
+    };
+  }
+  return {
+    migrated,
+    perField,
+    skippedDimensionMismatch,
+    skippedDecodeError,
+    legacyTablePresent: true
+  };
+}
+async function readLegacyBatch(backend, params) {
+  const table = quotedTableName(params.legacyTableName);
+  const embeddingJson = legacyEmbeddingDecodeExpression(backend);
+  const conditions = [];
+  if (params.graphId !== void 0) {
+    conditions.push(sql`"graph_id" = ${params.graphId}`);
+  }
+  if (params.after !== void 0) {
+    conditions.push(keysetAfterCondition(params.after));
+  }
+  const whereClause = conditions.length === 0 ? sql`` : sql` WHERE ${sql.join(conditions, sql` AND `)}`;
+  const query = sql`
+    SELECT
+      "graph_id" AS graph_id,
+      "node_kind" AS node_kind,
+      "node_id" AS node_id,
+      "field_path" AS field_path,
+      ${embeddingJson} AS embedding_json
+    FROM ${table}${whereClause}
+    ORDER BY "graph_id" ASC, "node_kind" ASC, "node_id" ASC, "field_path" ASC
+    LIMIT ${params.batchSize}
+  `;
+  return backend.execute(query);
+}
+function keysetAfterCondition(after) {
+  return sql`
+    (
+        "graph_id" > ${after.graphId}
+        OR ("graph_id" = ${after.graphId} AND "node_kind" > ${after.nodeKind})
+        OR ("graph_id" = ${after.graphId} AND "node_kind" = ${after.nodeKind} AND "node_id" > ${after.nodeId})
+        OR (
+          "graph_id" = ${after.graphId}
+          AND "node_kind" = ${after.nodeKind}
+          AND "node_id" = ${after.nodeId}
+          AND "field_path" > ${after.fieldPath}
+        )
+      )
+  `;
+}
+function legacyEmbeddingDecodeExpression(backend) {
+  switch (backend.dialect) {
+    case "sqlite": {
+      return sql`vec_to_json("embedding")`;
+    }
+    case "postgres": {
+      return sql`"embedding"::text`;
+    }
+    default: {
+      const _exhaustive = backend.dialect;
+      throw new Error(
+        `migrateLegacyEmbeddings does not support dialect: ${String(_exhaustive)}`
+      );
+    }
+  }
+}
+function decodeEmbeddingJson(row) {
+  let parsed;
+  try {
+    parsed = JSON.parse(row.embedding_json);
+  } catch (error) {
+    throw new Error(
+      `Failed to decode legacy embedding for ${row.node_kind}.${row.field_path} (graph ${row.graph_id}, node ${row.node_id}): not valid JSON.`,
+      { cause: error }
+    );
+  }
+  if (!Array.isArray(parsed) || parsed.length === 0) {
+    throw new Error(
+      `Legacy embedding for ${row.node_kind}.${row.field_path} (graph ${row.graph_id}, node ${row.node_id}) decoded to a non-array or empty value.`
+    );
+  }
+  for (const [index, value] of parsed.entries()) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+      throw new TypeError(
+        `Legacy embedding for ${row.node_kind}.${row.field_path} (graph ${row.graph_id}, node ${row.node_id}) has a non-finite value at index ${index}: ${String(value)}.`
+      );
+    }
+  }
+  return parsed;
+}
 
 // src/query/subquery-utils.ts
 function normalizeValueType(valueType) {
@@ -371,7 +552,10 @@ function vectorSimilarity(field2, queryEmbedding, limit, options) {
     __type: "vector_similarity",
     field: field2,
     queryEmbedding,
-    metric: options?.metric ?? "cosine",
+    // Leave metric unset when the caller didn't specify one, so the compiler
+    // resolves the field's declared metric per kind. Defaulting to "cosine"
+    // here would mis-rank l2/inner_product fields and bypass their ANN index.
+    ...options?.metric !== void 0 && { metric: options.metric },
     limit,
     ...options?.minScore !== void 0 && { minScore: options.minScore }
   };
@@ -1614,7 +1798,6 @@ function mergeEdgeKinds(traversal) {
 var DEFAULT_TABLE_NAMES = {
   nodes: "typegraph_nodes",
   edges: "typegraph_edges",
-  embeddings: "typegraph_node_embeddings",
   fulltext: "typegraph_node_fulltext",
   uniques: "typegraph_node_uniques"
 };
@@ -1641,18 +1824,19 @@ function createSqlSchema(names = {}) {
   const tables = { ...DEFAULT_TABLE_NAMES, ...names };
   validateTableName(tables.nodes, "nodes");
   validateTableName(tables.edges, "edges");
-  validateTableName(tables.embeddings, "embeddings");
   validateTableName(tables.fulltext, "fulltext");
   validateTableName(tables.uniques, "uniques");
   return {
     tables,
     nodesTable: sql.raw(quoteIdentifier2(tables.nodes)),
     edgesTable: sql.raw(quoteIdentifier2(tables.edges)),
-    embeddingsTable: sql.raw(quoteIdentifier2(tables.embeddings)),
     fulltextTable: sql.raw(quoteIdentifier2(tables.fulltext))
   };
 }
 var DEFAULT_SQL_SCHEMA = createSqlSchema();
+function vectorSlotKey(nodeKind, fieldPath) {
+  return `${nodeKind}\0${fieldPath}`;
+}
 var ALIAS_CTE_PREFIX = "cte_";
 var EMBEDDINGS_CTE_ALIAS = "cte_embeddings";
 var FULLTEXT_CTE_ALIAS = "cte_fulltext";
@@ -2159,35 +2343,61 @@ function buildStandardHaving(input) {
 }
 function buildStandardEmbeddingsCte(input) {
   const { ctx, graphId, nodeKinds, vectorPredicate } = input;
-  const { dialect } = ctx;
   const { field: field2, metric, minScore, queryEmbedding } = vectorPredicate;
-  const embeddingsTableName = ctx.schema.tables.embeddings;
   if (nodeKinds.length === 0) {
     throw new UnsupportedPredicateError(
       "Vector predicate must resolve to at least one node kind"
     );
   }
-  const fieldPath = resolveEmbeddingFieldPath(field2);
-  const distanceExpr = dialect.vectorDistance(
-    qualifyColumn(embeddingsTableName, "embedding"),
-    queryEmbedding,
-    metric
-  );
-  const scopedNodes = buildScopedNodeIdsSubquery(field2.alias);
-  const conditions = [
-    sql`${qualifyColumn(embeddingsTableName, "graph_id")} = ${graphId}`,
-    compileKindFilter(
-      qualifyColumn(embeddingsTableName, "node_kind"),
-      nodeKinds
-    ),
-    sql`${qualifyColumn(embeddingsTableName, "field_path")} = ${fieldPath}`
-  ];
-  if (minScore !== void 0) {
-    conditions.push(
-      compileVectorMinScoreCondition(distanceExpr, metric, minScore)
+  const { vectorStrategy } = ctx;
+  if (vectorStrategy === void 0) {
+    throw new UnsupportedPredicateError(
+      "Vector similarity predicate requires a backend with a vector strategy"
     );
   }
-  const scoreExpr = compileVectorScoreExpression(distanceExpr, metric);
+  const fieldPath = resolveEmbeddingFieldPath(field2);
+  const vectorSlots = ctx.vectorSlots;
+  const scopedNodes = buildScopedNodeIdsSubquery(field2.alias);
+  const declaringKinds = nodeKinds.filter(
+    (kind) => vectorSlots?.has(vectorSlotKey(kind, fieldPath))
+  );
+  const branches = declaringKinds.map((kind) => {
+    const tableName = vectorStrategy.tableName(graphId, kind, fieldPath);
+    const branchMetric = metric ?? vectorSlots?.get(vectorSlotKey(kind, fieldPath))?.metric ?? "cosine";
+    const distanceExpr = vectorStrategy.distanceExpression(
+      qualifyColumn(tableName, "embedding"),
+      queryEmbedding,
+      branchMetric
+    );
+    const scoreExpr = vectorScoreExpression(distanceExpr, branchMetric);
+    const conditions = [
+      sql`${qualifyColumn(tableName, "graph_id")} = ${graphId}`
+    ];
+    if (minScore !== void 0) {
+      conditions.push(
+        vectorMinScoreCondition(distanceExpr, branchMetric, minScore)
+      );
+    }
+    return sql`
+      SELECT
+        ${qualifyColumn(tableName, "node_id")} AS node_id,
+        ${kind} AS node_kind,
+        ${distanceExpr} AS distance,
+        ${scoreExpr} AS score
+      FROM ${quoteIdentifier(tableName)}
+      INNER JOIN ${scopedNodes}
+        ON ${sql.raw(`${SCOPED_RELEVANCE_NODES_ALIAS}.node_id`)} =
+           ${qualifyColumn(tableName, "node_id")}
+       AND ${sql.raw(`${SCOPED_RELEVANCE_NODES_ALIAS}.node_kind`)} = ${kind}
+      WHERE ${sql.join(conditions, sql` AND `)}
+    `;
+  });
+  const unionBody = branches.length === 0 ? emptyEmbeddingsBody() : sql.join(
+    branches,
+    sql`
+          UNION ALL
+        `
+  );
   return sql`
     ${sql.raw(EMBEDDINGS_CTE_ALIAS)} AS (
       SELECT
@@ -2197,49 +2407,22 @@ function buildStandardEmbeddingsCte(input) {
         score,
         ROW_NUMBER() OVER (ORDER BY distance ASC) AS ord
       FROM (
-        SELECT
-          ${qualifyColumn(embeddingsTableName, "node_id")} AS node_id,
-          ${qualifyColumn(embeddingsTableName, "node_kind")} AS node_kind,
-          ${distanceExpr} AS distance,
-          ${scoreExpr} AS score
-        FROM ${ctx.schema.embeddingsTable}
-        INNER JOIN ${scopedNodes}
-          ON ${sql.raw(`${SCOPED_RELEVANCE_NODES_ALIAS}.node_id`)} =
-             ${qualifyColumn(embeddingsTableName, "node_id")}
-         AND ${sql.raw(`${SCOPED_RELEVANCE_NODES_ALIAS}.node_kind`)} =
-             ${qualifyColumn(embeddingsTableName, "node_kind")}
-        WHERE ${sql.join(conditions, sql` AND `)}
+        ${unionBody}
         ORDER BY distance ASC
         LIMIT ${vectorPredicate.limit}
       ) AS vec_inner
     )
   `;
 }
-function compileVectorScoreExpression(distanceExpr, metric) {
-  switch (metric) {
-    case "cosine": {
-      return sql`(1.0 - ${distanceExpr})`;
-    }
-    case "l2":
-    case "inner_product": {
-      return distanceExpr;
-    }
-  }
-}
-function compileVectorMinScoreCondition(distanceExpr, metric, minScore) {
-  switch (metric) {
-    case "cosine": {
-      const threshold = 1 - minScore;
-      return sql`${distanceExpr} <= ${threshold}`;
-    }
-    case "l2": {
-      return sql`${distanceExpr} <= ${minScore}`;
-    }
-    case "inner_product": {
-      const negativeThreshold = -minScore;
-      return sql`${distanceExpr} <= ${negativeThreshold}`;
-    }
-  }
+function emptyEmbeddingsBody() {
+  return sql`
+    SELECT
+      CAST(NULL AS TEXT) AS node_id,
+      CAST(NULL AS TEXT) AS node_kind,
+      CAST(NULL AS REAL) AS distance,
+      CAST(NULL AS REAL) AS score
+    WHERE 1 = 0
+  `;
 }
 function buildStandardFulltextCte(input) {
   const { ctx, fulltextPredicate, graphId, nodeKinds } = input;
@@ -2406,6 +2589,11 @@ function runFulltextPredicatePass(ast, dialect) {
       `Fulltext query mode "${fulltextPredicate.mode}" is not supported by the "${strategy.name}" strategy. Supported modes: ${strategy.supportedModes.join(", ")}.`
     );
   }
+  if (fulltextPredicate.language !== void 0 && !strategy.supportsLanguageOverride) {
+    throw new UnsupportedPredicateError(
+      `Fulltext strategy "${strategy.name}" does not honor a per-query \`language\` override (its tokenizer is fixed at table-create time). Drop the option, or use a strategy that advertises \`supportsLanguageOverride: true\`.`
+    );
+  }
   if (!Number.isFinite(fulltextPredicate.limit) || fulltextPredicate.limit <= 0) {
     throw new UnsupportedPredicateError(
       `Fulltext match limit must be a positive finite number, got ${String(fulltextPredicate.limit)}`
@@ -2516,7 +2704,7 @@ function createTemporalFilterPass(ast, currentTimestamp) {
 }
 
 // src/query/compiler/passes/vector.ts
-function runVectorPredicatePass(ast, dialect) {
+function runVectorPredicatePass(ast, dialect, vectorStrategy) {
   const vectorPredicates = extractVectorSimilarityPredicates(ast.predicates);
   if (vectorPredicates.length > 1) {
     throw new UnsupportedPredicateError(
@@ -2527,16 +2715,19 @@ function runVectorPredicatePass(ast, dialect) {
   if (vectorPredicate === void 0) {
     return { vectorPredicate: void 0 };
   }
-  const vectorStrategy = dialect.capabilities.vectorPredicateStrategy;
-  if (vectorStrategy === "unsupported" || !dialect.supportsVectors) {
+  const predicateStrategy = dialect.capabilities.vectorPredicateStrategy;
+  if (predicateStrategy === "unsupported" || !dialect.supportsVectors) {
     throw new UnsupportedPredicateError(
       `Vector similarity predicates are not supported for dialect "${dialect.name}"`
     );
   }
-  if (!dialect.capabilities.vectorMetrics.includes(vectorPredicate.metric)) {
-    throw new UnsupportedPredicateError(
-      `Vector metric "${vectorPredicate.metric}" is not supported for dialect "${dialect.name}"`
-    );
+  if (vectorPredicate.metric !== void 0) {
+    const supportedMetrics = vectorStrategy?.capabilities.metrics ?? dialect.capabilities.vectorMetrics;
+    if (!supportedMetrics.includes(vectorPredicate.metric)) {
+      throw new UnsupportedPredicateError(
+        vectorStrategy === void 0 ? `Vector metric "${vectorPredicate.metric}" is not supported for dialect "${dialect.name}"` : `Vector metric "${vectorPredicate.metric}" is not supported by vector strategy "${vectorStrategy.name}" (supported: ${supportedMetrics.join(", ")})`
+      );
+    }
   }
   if (!Number.isFinite(vectorPredicate.limit) || vectorPredicate.limit <= 0) {
     throw new UnsupportedPredicateError(
@@ -2781,13 +2972,14 @@ function lowerRecursiveQueryToLogicalPlanNode(input) {
     ast.limit
   );
 }
-function lowerComposableQueryToLogicalPlanNode(query, dialect, graphId, nextPlanNodeId) {
+function lowerComposableQueryToLogicalPlanNode(query, dialect, graphId, nextPlanNodeId, vectorStrategy) {
   if ("__type" in query) {
     return lowerSetOperationToLogicalPlanNode(
       query,
       graphId,
       dialect,
-      nextPlanNodeId
+      nextPlanNodeId,
+      vectorStrategy
     );
   }
   const hasVariableLengthTraversal2 = query.traversals.some(
@@ -2803,7 +2995,8 @@ function lowerComposableQueryToLogicalPlanNode(query, dialect, graphId, nextPlan
   const dialectAdapter = getDialect(dialect);
   const vectorPredicate = runVectorPredicatePass(
     query,
-    dialectAdapter
+    dialectAdapter,
+    vectorStrategy
   ).vectorPredicate;
   const fulltextPredicate = runFulltextPredicatePass(
     query,
@@ -2827,14 +3020,15 @@ function lowerComposableQueryToLogicalPlanNode(query, dialect, graphId, nextPlan
   };
   return lowerStandardQueryToLogicalPlanNode(loweringInput);
 }
-function lowerSetOperationToLogicalPlanNode(op, graphId, dialect, nextPlanNodeId) {
+function lowerSetOperationToLogicalPlanNode(op, graphId, dialect, nextPlanNodeId, vectorStrategy) {
   let currentNode = {
     id: nextPlanNodeId(),
     left: lowerComposableQueryToLogicalPlanNode(
       op.left,
       dialect,
       graphId,
-      nextPlanNodeId
+      nextPlanNodeId,
+      vectorStrategy
     ),
     op: "set_op",
     operator: op.operator,
@@ -2842,7 +3036,8 @@ function lowerSetOperationToLogicalPlanNode(op, graphId, dialect, nextPlanNodeId
       op.right,
       dialect,
       graphId,
-      nextPlanNodeId
+      nextPlanNodeId,
+      vectorStrategy
     )
   };
   if (op.orderBy !== void 0 && op.orderBy.length > 0) {
@@ -2906,7 +3101,8 @@ function lowerSetOperationToLogicalPlan(input) {
       input.op,
       input.graphId,
       input.dialect,
-      nextPlanNodeId
+      nextPlanNodeId,
+      input.vectorStrategy
     )
   };
 }
@@ -4480,29 +4676,7 @@ var OPERATOR_MAP = {
   intersect: "INTERSECT",
   except: "EXCEPT"
 };
-function compileSetOperationWithStandardParenthesizedStrategy(op, graphId, dialect, logicalPlan, _schema, compileQuery2) {
-  return compileSetOperationStandard(
-    op,
-    graphId,
-    dialect,
-    logicalPlan,
-    compileQuery2
-  );
-}
-function compileSetOperationWithSqliteCompoundStrategy(op, graphId, dialect, logicalPlan, schema, _compileQuery) {
-  return compileSetOperationForSqlite(
-    op,
-    graphId,
-    dialect,
-    logicalPlan,
-    schema
-  );
-}
-var SET_OPERATION_STRATEGY_HANDLERS = {
-  standard_parenthesized: compileSetOperationWithStandardParenthesizedStrategy,
-  sqlite_compound: compileSetOperationWithSqliteCompoundStrategy
-};
-function runSetOperationPassPipeline(op, graphId, dialect) {
+function runSetOperationPassPipeline(op, graphId, dialect, vectorStrategy) {
   let state = {
     dialect,
     graphId,
@@ -4515,7 +4689,8 @@ function runSetOperationPassPipeline(op, graphId, dialect) {
       return lowerSetOperationToLogicalPlan({
         dialect: currentState.dialect.name,
         graphId: currentState.graphId,
-        op: currentState.op
+        op: currentState.op,
+        ...vectorStrategy === void 0 ? {} : { vectorStrategy }
       });
     },
     update(currentState, logicalPlan) {
@@ -4528,25 +4703,20 @@ function runSetOperationPassPipeline(op, graphId, dialect) {
   state = logicalPlanPass.state;
   return state;
 }
-function compileSetOperation(op, graphId, dialect, schema, compileQuery2) {
-  const passState = runSetOperationPassPipeline(op, graphId, dialect);
+function compileSetOperation(op, graphId, dialect, compileQuery2, vectorStrategy) {
+  const passState = runSetOperationPassPipeline(
+    op,
+    graphId,
+    dialect,
+    vectorStrategy
+  );
   const { logicalPlan } = passState;
   if (logicalPlan === void 0) {
     throw new CompilerInvariantError(
       "Logical plan pass did not initialize plan state"
     );
   }
-  const strategy = dialect.capabilities.setOperationStrategy;
-  const handler = SET_OPERATION_STRATEGY_HANDLERS[strategy];
-  return handler(op, graphId, dialect, logicalPlan, schema, compileQuery2);
-}
-function compileSetOperationStandard(op, graphId, dialect, logicalPlan, compileQuery2) {
-  const coreSql = compileSetOperationCoreStandard(
-    op,
-    graphId,
-    dialect,
-    compileQuery2
-  );
+  const coreSql = compileSetOperationCore(op, graphId, compileQuery2, dialect);
   const suffixClauses = buildSetOperationSuffixClauses(op, dialect);
   return emitSetOperationQuerySql({
     baseQuery: coreSql,
@@ -4554,361 +4724,28 @@ function compileSetOperationStandard(op, graphId, dialect, logicalPlan, compileQ
     ...suffixClauses.length === 0 ? {} : { suffixClauses }
   });
 }
-function compileSetOperationCoreStandard(op, graphId, dialect, compileQuery2) {
-  const left = compileComposableQueryStandard(
-    op.left,
-    graphId,
-    dialect,
-    compileQuery2
-  );
-  const right = compileComposableQueryStandard(
+function compileSetOperationCore(op, graphId, compileQuery2, dialect) {
+  const left = compileComposableQuery(op.left, graphId, compileQuery2, dialect);
+  const right = compileComposableQuery(
     op.right,
     graphId,
-    dialect,
-    compileQuery2
+    compileQuery2,
+    dialect
   );
   const opSql = sql.raw(OPERATOR_MAP[op.operator]);
-  return sql`(${left}) ${opSql} (${right})`;
+  return sql`${dialect.wrapSetOperationOperand(left)} ${opSql} ${dialect.wrapSetOperationOperand(right)}`;
 }
-function compileComposableQueryStandard(query, graphId, dialect, compileQuery2) {
+function compileComposableQuery(query, graphId, compileQuery2, dialect) {
   if ("__type" in query) {
-    return compileSetOperationCoreStandard(
-      query,
-      graphId,
-      dialect,
-      compileQuery2
-    );
+    return compileSetOperationCompound(query, graphId, compileQuery2, dialect);
   }
   return compileQuery2(query, graphId);
 }
-function runSqliteSetOperationValidationPass(op) {
-  const leaves = [];
-  collectLeafQueries(op, leaves, "q");
-  for (const leaf of leaves) {
-    validateSqliteSetOpLeaf(leaf.ast);
-  }
-  return { leaves };
-}
-function compileSetOperationForSqlite(op, graphId, dialect, logicalPlan, schema) {
-  const { leaves } = runSqliteSetOperationValidationPass(op);
-  const allCtes = [];
-  const ctx = {
-    dialect,
-    schema,
-    compileQuery: () => {
-      throw new CompilerInvariantError(
-        "compileQuery is not available in set-operation CTE compilation"
-      );
-    }
-  };
-  for (const leaf of leaves) {
-    const cte = compilePrefixedStartCte(leaf.ast, leaf.prefix, graphId, ctx);
-    allCtes.push(cte);
-  }
-  const selectStatements = [];
-  for (const leaf of leaves) {
-    const select = compilePrefixedSelect(leaf.ast, leaf.prefix, dialect);
-    selectStatements.push(select);
-  }
-  const compoundSelect = buildCompoundSelect(op, leaves, selectStatements);
+function compileSetOperationCompound(op, graphId, compileQuery2, dialect) {
+  const core2 = compileSetOperationCore(op, graphId, compileQuery2, dialect);
   const suffixClauses = buildSetOperationSuffixClauses(op, dialect);
-  return emitSetOperationQuerySql({
-    baseQuery: compoundSelect,
-    ...allCtes.length === 0 ? {} : { ctes: allCtes },
-    logicalPlan,
-    ...suffixClauses.length === 0 ? {} : { suffixClauses }
-  });
-}
-function validateSqliteSetOpLeaf(ast) {
-  const unsupported = [];
-  if (ast.traversals.length > 0) {
-    unsupported.push("traversals");
-  }
-  if (hasSubqueryPredicates(ast)) {
-    unsupported.push("EXISTS/IN subqueries");
-  }
-  if (hasVectorSimilarityPredicates(ast)) {
-    unsupported.push("vector similarity predicates");
-  }
-  if (hasFulltextMatchPredicates(ast)) {
-    unsupported.push("fulltext match predicates");
-  }
-  if (ast.groupBy !== void 0) {
-    unsupported.push("GROUP BY");
-  }
-  if (ast.having !== void 0) {
-    unsupported.push("HAVING");
-  }
-  if (ast.orderBy !== void 0 && ast.orderBy.length > 0) {
-    unsupported.push(
-      "per-query ORDER BY (use set operation's orderBy instead)"
-    );
-  }
-  if (ast.limit !== void 0) {
-    unsupported.push("per-query LIMIT (use set operation's limit instead)");
-  }
-  if (ast.offset !== void 0) {
-    unsupported.push("per-query OFFSET (use set operation's offset instead)");
-  }
-  if (unsupported.length > 0) {
-    throw new UnsupportedPredicateError(
-      `SQLite set operations (UNION/INTERSECT/EXCEPT) do not support: ${unsupported.join(", ")}. Use PostgreSQL for complex set operations, or refactor to separate queries.`
-    );
-  }
-}
-function hasVectorSimilarityPredicates(ast) {
-  return ast.predicates.some(
-    (predicate2) => hasVectorSimilarityInExpression(predicate2.expression)
-  );
-}
-function hasVectorSimilarityInExpression(expr) {
-  if ("__type" in expr) {
-    switch (expr.__type) {
-      case "and":
-      case "or": {
-        return expr.predicates.some((p) => hasVectorSimilarityInExpression(p));
-      }
-      case "not": {
-        return hasVectorSimilarityInExpression(expr.predicate);
-      }
-      case "vector_similarity": {
-        return true;
-      }
-      case "exists":
-      case "in_subquery":
-      case "comparison":
-      case "string_op":
-      case "null_check":
-      case "between":
-      case "array_op":
-      case "object_op":
-      case "aggregate_comparison":
-      case "fulltext_match": {
-        return false;
-      }
-    }
-  }
-  return false;
-}
-function hasFulltextMatchPredicates(ast) {
-  return ast.predicates.some(
-    (predicate2) => hasFulltextMatchInExpression(predicate2.expression)
-  );
-}
-function hasFulltextMatchInExpression(expr) {
-  if ("__type" in expr) {
-    switch (expr.__type) {
-      case "and":
-      case "or": {
-        return expr.predicates.some((p) => hasFulltextMatchInExpression(p));
-      }
-      case "not": {
-        return hasFulltextMatchInExpression(expr.predicate);
-      }
-      case "fulltext_match": {
-        return true;
-      }
-      case "exists":
-      case "in_subquery":
-      case "comparison":
-      case "string_op":
-      case "null_check":
-      case "between":
-      case "array_op":
-      case "object_op":
-      case "aggregate_comparison":
-      case "vector_similarity": {
-        return false;
-      }
-    }
-  }
-  return false;
-}
-function hasSubqueryPredicates(ast) {
-  return ast.predicates.some(
-    (predicate2) => hasSubqueryInExpression(predicate2.expression)
-  );
-}
-function hasSubqueryInExpression(expr) {
-  if ("__type" in expr) {
-    switch (expr.__type) {
-      case "and":
-      case "or": {
-        return expr.predicates.some((p) => hasSubqueryInExpression(p));
-      }
-      case "not": {
-        return hasSubqueryInExpression(expr.predicate);
-      }
-      case "exists": {
-        return true;
-      }
-      case "in_subquery": {
-        return true;
-      }
-      // These expression types don't contain subqueries
-      case "comparison":
-      case "string_op":
-      case "null_check":
-      case "between":
-      case "array_op":
-      case "object_op":
-      case "aggregate_comparison":
-      case "vector_similarity":
-      case "fulltext_match": {
-        return false;
-      }
-    }
-  }
-  return false;
-}
-function collectLeafQueries(query, leaves, basePrefix) {
-  if ("__type" in query) {
-    collectLeafQueries(query.left, leaves, basePrefix);
-    collectLeafQueries(query.right, leaves, basePrefix);
-  } else {
-    const index = leaves.length;
-    leaves.push({ ast: query, prefix: `${basePrefix}${index}` });
-  }
-}
-function compilePrefixedStartCte(ast, prefix, graphId, ctx) {
-  const temporalFilterPass = createTemporalFilterPass(
-    ast,
-    ctx.dialect.currentTimestamp()
-  );
-  const alias = ast.start.alias;
-  const kinds = ast.start.kinds;
-  const kindFilter = kinds.length === 1 ? sql`kind = ${kinds[0]}` : sql`kind IN (${sql.join(
-    kinds.map((k) => sql`${k}`),
-    sql`, `
-  )})`;
-  const temporalFilter = temporalFilterPass.forAlias();
-  const cteContext = { ...ctx, cteColumnPrefix: "" };
-  const predicateClauses = ast.predicates.filter((p) => p.targetAlias === alias).map((p) => compilePredicateExpression(p.expression, cteContext));
-  const whereClauses = [
-    sql`graph_id = ${graphId}`,
-    kindFilter,
-    temporalFilter,
-    ...predicateClauses
-  ];
-  const cteName = `cte_${prefix}_${alias}`;
-  return sql`
-    ${sql.raw(cteName)} AS (
-      SELECT
-        id AS ${sql.raw(alias)}_id,
-        kind AS ${sql.raw(alias)}_kind,
-        props AS ${sql.raw(alias)}_props,
-        version AS ${sql.raw(alias)}_version,
-        valid_from AS ${sql.raw(alias)}_valid_from,
-        valid_to AS ${sql.raw(alias)}_valid_to,
-        created_at AS ${sql.raw(alias)}_created_at,
-        updated_at AS ${sql.raw(alias)}_updated_at,
-        deleted_at AS ${sql.raw(alias)}_deleted_at
-      FROM ${ctx.schema.nodesTable}
-      WHERE ${sql.join(whereClauses, sql` AND `)}
-    )
-  `;
-}
-function compilePrefixedSelect(ast, prefix, dialect) {
-  const alias = ast.start.alias;
-  const cteName = `cte_${prefix}_${alias}`;
-  const fields = ast.projection.fields;
-  const projection = fields.length === 0 ? sql.raw("*") : sql.join(
-    fields.map((f) => {
-      const source = compileFieldValueForSetOp(
-        f.source,
-        prefix,
-        alias,
-        dialect
-      );
-      return sql`${source} AS ${sql.raw(dialect.quoteIdentifier(f.outputName))}`;
-    }),
-    sql`, `
-  );
-  return sql`SELECT ${projection} FROM ${sql.raw(cteName)}`;
-}
-function compileFieldValueForSetOp(source, prefix, alias, dialect) {
-  if ("__type" in source && source.__type === "aggregate") {
-    const { field: field2, function: fn } = source;
-    switch (fn) {
-      case "count":
-      case "countDistinct":
-      case "sum":
-      case "avg":
-      case "min":
-      case "max": {
-        const column = compileFieldColumnForSetOp(field2, prefix, dialect);
-        if (fn === "countDistinct") {
-          return sql`COUNT(DISTINCT ${column})`;
-        }
-        return sql`${sql.raw(fn.toUpperCase())}(${column})`;
-      }
-      default: {
-        throw new CompilerInvariantError(
-          `Unknown aggregate function: ${String(fn)}`
-        );
-      }
-    }
-  }
-  return compileFieldColumnForSetOp(source, prefix, dialect);
-}
-function compileFieldColumnForSetOp(field2, prefix, dialect) {
-  const cteName = `cte_${prefix}_${field2.alias}`;
-  const alias = field2.alias;
-  if (field2.path.length === 1) {
-    const columnName = field2.path[0];
-    const columnMap = {
-      id: "_id",
-      kind: "_kind",
-      props: "_props",
-      version: "_version",
-      valid_from: "_valid_from",
-      valid_to: "_valid_to",
-      created_at: "_created_at",
-      updated_at: "_updated_at",
-      deleted_at: "_deleted_at"
-    };
-    if (columnName === void 0) return sql.raw(`${cteName}.${alias}_props`);
-    const suffix = columnMap[columnName];
-    if (suffix) {
-      return sql.raw(`${cteName}.${alias}${suffix}`);
-    }
-  }
-  const column = sql.raw(`${cteName}.${alias}_props`);
-  const pointer = field2.jsonPointer;
-  if (!pointer) {
-    return column;
-  }
-  return compileTypedJsonExtract({
-    column,
-    dialect,
-    fallback: "text",
-    pointer,
-    valueType: field2.valueType
-  });
-}
-function buildCompoundSelect(op, leaves, selectStatements) {
-  const prefixToSelect = /* @__PURE__ */ new Map();
-  for (const [index, leaf] of leaves.entries()) {
-    prefixToSelect.set(leaf.prefix, selectStatements[index]);
-  }
-  return buildCompoundSelectRecursive(op, leaves, prefixToSelect);
-}
-function buildCompoundSelectRecursive(query, leaves, prefixToSelect) {
-  if (!("__type" in query)) {
-    const leaf = leaves.find((l) => l.ast === query);
-    if (!leaf) {
-      throw new CompilerInvariantError("Leaf query not found in leaves array");
-    }
-    return prefixToSelect.get(leaf.prefix);
-  }
-  const left = buildCompoundSelectRecursive(query.left, leaves, prefixToSelect);
-  const right = buildCompoundSelectRecursive(
-    query.right,
-    leaves,
-    prefixToSelect
-  );
-  const opSql = sql.raw(OPERATOR_MAP[query.operator]);
-  return sql`${left} ${opSql} ${right}`;
+  if (suffixClauses.length === 0) return core2;
+  return sql.join([core2, ...suffixClauses], sql` `);
 }
 function getLeftmostProjection(op) {
   let current = op.left;
@@ -5201,7 +5038,11 @@ function runStandardQueryPassPipeline(ast, graphId, ctx) {
   const vectorPass = runCompilerPass(state, {
     name: "vector_predicate",
     execute(currentState) {
-      return runVectorPredicatePass(currentState.ast, currentState.ctx.dialect).vectorPredicate;
+      return runVectorPredicatePass(
+        currentState.ast,
+        currentState.ctx.dialect,
+        currentState.ctx.vectorStrategy
+      ).vectorPredicate;
     },
     update(currentState, vectorPredicate) {
       return {
@@ -5358,7 +5199,9 @@ function compileQuery(ast, graphId, options = "sqlite") {
   const ctx = {
     dialect: adapter,
     schema,
-    compileQuery: (subAst, subGraphId) => compileQuery(subAst, subGraphId, propagateOptions(options_))
+    compileQuery: (subAst, subGraphId) => compileQuery(subAst, subGraphId, propagateOptions(options_)),
+    ...options_.vectorStrategy === void 0 ? {} : { vectorStrategy: options_.vectorStrategy },
+    ...options_.vectorSlots === void 0 ? {} : { vectorSlots: options_.vectorSlots }
   };
   if (hasVariableLengthTraversal(ast)) {
     const lowered = tryLowerSingleHopRecursiveTraversal(ast);
@@ -5393,14 +5236,13 @@ function tryLowerSingleHopRecursiveTraversal(ast) {
 function compileSetOperation2(op, graphId, options = "sqlite") {
   const options_ = typeof options === "string" ? { dialect: options } : options;
   const dialect = options_.dialect ?? "sqlite";
-  const schema = options_.schema ?? DEFAULT_SQL_SCHEMA;
   const adapter = resolveDialectAdapter(dialect, options_.fulltextStrategy);
   return compileSetOperation(
     op,
     graphId,
     adapter,
-    schema,
-    (ast, gid) => compileQuery(ast, gid, propagateOptions(options_))
+    (ast, gid) => compileQuery(ast, gid, propagateOptions(options_)),
+    options_.vectorStrategy
   );
 }
 function resolveDialectAdapter(dialect, fulltextStrategy) {
@@ -5414,7 +5256,9 @@ function propagateOptions(options_) {
   return {
     dialect: options_.dialect ?? "sqlite",
     ...options_.schema === void 0 ? {} : { schema: options_.schema },
-    ...options_.fulltextStrategy === void 0 ? {} : { fulltextStrategy: options_.fulltextStrategy }
+    ...options_.fulltextStrategy === void 0 ? {} : { fulltextStrategy: options_.fulltextStrategy },
+    ...options_.vectorStrategy === void 0 ? {} : { vectorStrategy: options_.vectorStrategy },
+    ...options_.vectorSlots === void 0 ? {} : { vectorSlots: options_.vectorSlots }
   };
 }
 function resolveCountAggregateFastPath(ast) {
@@ -7005,12 +6849,31 @@ function buildQueryAst(config, state) {
 // src/query/builder/compile-options.ts
 function buildCompileOptions(config) {
   const fulltextStrategy = config.backend?.fulltextStrategy;
+  const vectorStrategy = config.backend?.vectorStrategy;
   return {
     dialect: config.dialect ?? "sqlite",
     schema: config.schema,
-    ...fulltextStrategy === void 0 ? {} : { fulltextStrategy }
+    ...fulltextStrategy === void 0 ? {} : { fulltextStrategy },
+    ...vectorStrategy === void 0 ? {} : { vectorStrategy, vectorSlots: buildVectorSlots(config.registry) }
   };
 }
+var vectorSlotsCache = /* @__PURE__ */ new WeakMap();
+function buildVectorSlots(registry) {
+  const cached = vectorSlotsCache.get(registry);
+  if (cached !== void 0) return cached;
+  const slots = /* @__PURE__ */ new Map();
+  for (const [nodeKind, nodeType] of registry.nodeKinds) {
+    for (const field2 of resolveEmbeddingFields(nodeType.schema)) {
+      slots.set(vectorSlotKey(nodeKind, field2.fieldPath), {
+        dimensions: field2.dimensions,
+        metric: field2.metric,
+        indexType: field2.indexType
+      });
+    }
+  }
+  vectorSlotsCache.set(registry, slots);
+  return slots;
+}
 function toLiteral(value) {
   if (value === null) {
     throw new ConfigurationError(
@@ -11212,7 +11075,7 @@ async function materializeVectorIndex(declaration, backend, graphId, schemaVersi
     );
   }
   const vectorCapability = backend.capabilities.vector;
-  if (vectorCapability?.supported !== true || backend.createVectorIndex === void 0) {
+  if (vectorCapability?.supported !== true || backend.createVectorIndex === void 0 || backend.vectorStrategy === void 0) {
     return skippedEntry(
       declaration,
       `Backend (${backend.dialect}) does not support vector indexes in its current configuration`
@@ -11224,7 +11087,11 @@ async function materializeVectorIndex(declaration, backend, graphId, schemaVersi
       `Backend (${backend.dialect}) does not support index type "${declaration.indexType}" for vector indexes; supported: ${vectorCapability.indexTypes.join(", ") || "(none)"}`
     );
   }
-  const embeddingsTable = backend.tableNames?.embeddings ?? "typegraph_node_embeddings";
+  const embeddingsTable = backend.vectorStrategy.tableName(
+    graphId,
+    declaration.kind,
+    declaration.fieldPath
+  );
   const signature = await computeIndexSignature(
     backend.dialect,
     embeddingsTable,
@@ -11387,16 +11254,16 @@ async function materializeRemovals(context, options = {}) {
   }
   await ensureFocusedStatusTable(backend, backend.ensureKindRemovalsTable);
   await reconcilePendingRemovals(context);
+  const reclaimedVectorFields = await reclaimRemovedVectorFieldTables(context);
   const pending = await backend.getPendingKindRemovals(graphId);
   const kindFilter = options.kinds === void 0 ? void 0 : new Set(options.kinds);
   const candidates = pending.filter(
     (row) => kindFilter === void 0 ? true : kindFilter.has(row.kindName)
   );
-  if (candidates.length === 0) return { results: [] };
+  if (candidates.length === 0) return { results: [], reclaimedVectorFields };
   const tableNames = backend.tableNames;
   const nodesTable = tableNames?.nodes ?? "typegraph_nodes";
   const edgesTable = tableNames?.edges ?? "typegraph_edges";
-  const embeddingsTable = tableNames?.embeddings ?? "typegraph_node_embeddings";
   const fulltextTable = tableNames?.fulltext ?? "typegraph_node_fulltext";
   const uniquesTable = tableNames?.uniques ?? "typegraph_node_uniques";
   const ctx = {
@@ -11404,7 +11271,6 @@ async function materializeRemovals(context, options = {}) {
     graphId,
     nodesTable,
     edgesTable,
-    embeddingsTable,
     fulltextTable,
     uniquesTable
   };
@@ -11413,7 +11279,8 @@ async function materializeRemovals(context, options = {}) {
       candidates,
       options,
       (removal) => materializeOne2(removal, ctx)
-    )
+    ),
+    reclaimedVectorFields
   };
 }
 async function reconcilePendingRemovals(context) {
@@ -11500,15 +11367,13 @@ async function materializeOne2(row, ctx) {
         executeDdl(
           `DELETE FROM ${quote(ctx.edgesTable)} WHERE graph_id = ${graphLit} AND (from_kind = ${kindLit} OR to_kind = ${kindLit})`
         ),
-        executeDdl(
-          `DELETE FROM ${quote(ctx.embeddingsTable)} WHERE graph_id = ${graphLit} AND node_kind = ${kindLit}`
-        ),
         executeDdl(
           `DELETE FROM ${quote(ctx.fulltextTable)} WHERE graph_id = ${graphLit} AND node_kind = ${kindLit}`
         ),
         executeDdl(
           `DELETE FROM ${quote(ctx.uniquesTable)} WHERE graph_id = ${graphLit} AND node_kind = ${kindLit}`
-        )
+        ),
+        ...buildEmbeddingTableCleanup(ctx, row)
       );
     } else {
       deletes.push(
@@ -11552,6 +11417,128 @@ async function materializeOne2(row, ctx) {
     };
   }
 }
+function buildEmbeddingTableCleanup(ctx, row) {
+  const vectorStrategy = ctx.backend.vectorStrategy;
+  if (vectorStrategy === void 0) return [];
+  const executeDdl = ctx.backend.executeDdl;
+  const cleanup = (async () => {
+    const slots = await resolveRemovedKindEmbeddingSlots(ctx.backend, row);
+    await Promise.all(
+      slots.map(
+        (slot) => dropVectorSlotStorage(vectorStrategy, executeDdl, slot)
+      )
+    );
+  })();
+  return [cleanup];
+}
+async function dropVectorSlotStorage(strategy, executeDdl, slot) {
+  try {
+    for (const ddl of strategy.buildDropStorage(slot)) {
+      await executeDdl(ddl);
+    }
+  } catch (error) {
+    if (!isMissingTableError(error)) throw error;
+  }
+}
+async function resolveRemovedKindEmbeddingSlots(backend, row) {
+  const priorVersion = row.schemaVersion - 1;
+  if (priorVersion < 1) return [];
+  const priorRow = await backend.getSchemaVersion(row.graphId, priorVersion);
+  if (priorRow === void 0) return [];
+  const priorSchema = parseSerializedSchema(priorRow.schema_doc);
+  const slots = /* @__PURE__ */ new Map();
+  for (const declaration of priorSchema.indexes ?? []) {
+    if (declaration.entity === "vector" && declaration.kind === row.kindName) {
+      slots.set(declaration.fieldPath, {
+        graphId: row.graphId,
+        nodeKind: row.kindName,
+        fieldPath: declaration.fieldPath,
+        dimensions: declaration.dimensions,
+        metric: declaration.metric,
+        indexType: declaration.indexType
+      });
+    }
+  }
+  return [...slots.values()];
+}
+function vectorFieldKey(kind, fieldPath) {
+  return `${kind}\0${fieldPath}`;
+}
+async function reclaimRemovedVectorFieldTables(context) {
+  const { backend, graphId } = context;
+  const vectorStrategy = backend.vectorStrategy;
+  const executeDdl = backend.executeDdl;
+  if (vectorStrategy === void 0 || executeDdl === void 0) return [];
+  const activeRow = await backend.getActiveSchema(graphId);
+  if (activeRow === void 0) return [];
+  const cacheKey = `${graphId}\0${activeRow.version}`;
+  let perBackend = reclaimCache.get(backend);
+  const cached = perBackend?.get(cacheKey);
+  if (cached !== void 0) return cached;
+  const activeSchema = parseSerializedSchema(activeRow.schema_doc);
+  const activeVectorFields = /* @__PURE__ */ new Set();
+  for (const declaration of activeSchema.indexes ?? []) {
+    if (declaration.entity === "vector") {
+      activeVectorFields.add(
+        vectorFieldKey(declaration.kind, declaration.fieldPath)
+      );
+    }
+  }
+  const survivingKinds = new Set(Object.keys(activeSchema.nodes));
+  const historical = /* @__PURE__ */ new Map();
+  for (let version = activeRow.version - 1; version >= 1; version -= 1) {
+    const priorRow = await backend.getSchemaVersion(graphId, version);
+    if (priorRow === void 0) continue;
+    const priorSchema = parseSerializedSchema(priorRow.schema_doc);
+    for (const declaration of priorSchema.indexes ?? []) {
+      if (declaration.entity !== "vector") continue;
+      const key = vectorFieldKey(declaration.kind, declaration.fieldPath);
+      if (historical.has(key)) continue;
+      historical.set(key, {
+        kind: declaration.kind,
+        fieldPath: declaration.fieldPath,
+        slot: {
+          graphId,
+          nodeKind: declaration.kind,
+          fieldPath: declaration.fieldPath,
+          dimensions: declaration.dimensions,
+          metric: declaration.metric,
+          indexType: declaration.indexType
+        }
+      });
+    }
+  }
+  const orphans = [...historical.values()].filter(
+    (field2) => !activeVectorFields.has(vectorFieldKey(field2.kind, field2.fieldPath)) && survivingKinds.has(field2.kind)
+  );
+  const results = [];
+  for (const field2 of orphans) {
+    try {
+      await dropVectorSlotStorage(vectorStrategy, executeDdl, field2.slot);
+      results.push({
+        kind: field2.kind,
+        fieldPath: field2.fieldPath,
+        status: "reclaimed"
+      });
+    } catch (error) {
+      results.push({
+        kind: field2.kind,
+        fieldPath: field2.fieldPath,
+        status: "failed",
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    }
+  }
+  if (results.every((entry2) => entry2.status === "reclaimed")) {
+    if (perBackend === void 0) {
+      perBackend = /* @__PURE__ */ new Map();
+      reclaimCache.set(backend, perBackend);
+    }
+    perBackend.set(cacheKey, results);
+  }
+  return results;
+}
+var reclaimCache = /* @__PURE__ */ new WeakMap();
 function quote(identifier) {
   return `"${identifier.replaceAll('"', '""')}"`;
 }
@@ -12536,46 +12523,10 @@ var embeddingFieldsCache = /* @__PURE__ */ new WeakMap();
 function getEmbeddingFields(schema) {
   const cached = embeddingFieldsCache.get(schema);
   if (cached) return cached;
-  const fields = computeEmbeddingFields(schema);
+  const fields = resolveEmbeddingFields(schema);
   embeddingFieldsCache.set(schema, fields);
   return fields;
 }
-function computeEmbeddingFields(schema) {
-  if (schema.type !== "object") return [];
-  const def = schema.def;
-  const shape = def.shape;
-  if (!shape) return [];
-  const fields = [];
-  for (const [fieldPath, fieldSchema] of Object.entries(shape)) {
-    const dimensions = getEmbeddingDimensionsFromField(fieldSchema);
-    if (dimensions !== void 0) {
-      fields.push({ fieldPath, dimensions });
-    }
-  }
-  return fields;
-}
-function getEmbeddingDimensionsFromField(schema) {
-  const directDimensions = getEmbeddingDimensions(schema);
-  if (directDimensions !== void 0) {
-    return directDimensions;
-  }
-  const unwrapped = unwrapToEmbedding(schema);
-  if (unwrapped) {
-    return getEmbeddingDimensions(unwrapped);
-  }
-  return void 0;
-}
-function unwrapToEmbedding(schema) {
-  const type = schema.type;
-  const def = schema.def;
-  if ((type === "optional" || type === "nullable" || type === "default" || type === "readonly") && def.innerType) {
-    if (isEmbeddingSchema(def.innerType)) {
-      return def.innerType;
-    }
-    return unwrapToEmbedding(def.innerType);
-  }
-  return void 0;
-}
 async function syncEmbeddings(ctx, schema, props) {
   const { backend } = ctx;
   if (!backend.upsertEmbedding || !backend.deleteEmbedding) {
@@ -12594,14 +12545,19 @@ async function syncEmbeddings(ctx, schema, props) {
         nodeId: ctx.nodeId,
         fieldPath: field2.fieldPath,
         embedding: value,
-        dimensions: field2.dimensions
+        dimensions: field2.dimensions,
+        metric: field2.metric,
+        indexType: field2.indexType
       });
     } else if (value === void 0) {
       await backend.deleteEmbedding({
         graphId: ctx.graphId,
         nodeKind: ctx.nodeKind,
         nodeId: ctx.nodeId,
-        fieldPath: field2.fieldPath
+        fieldPath: field2.fieldPath,
+        dimensions: field2.dimensions,
+        metric: field2.metric,
+        indexType: field2.indexType
       });
     }
   }
@@ -12620,7 +12576,10 @@ async function deleteNodeEmbeddings(ctx, schema) {
       graphId: ctx.graphId,
       nodeKind: ctx.nodeKind,
       nodeId: ctx.nodeId,
-      fieldPath: field2.fieldPath
+      fieldPath: field2.fieldPath,
+      dimensions: field2.dimensions,
+      metric: field2.metric,
+      indexType: field2.indexType
     });
   }
 }
@@ -13360,6 +13319,10 @@ async function executeNodeHardDelete(ctx, kind, id, backend) {
     await enforceDeleteBehavior(ctx, kind, id, "hard", backend, registration);
     const hardDelete = async (target) => {
       await target.hardDeleteNode({ graphId: ctx.graphId, kind, id });
+      await deleteNodeEmbeddings(
+        createEmbeddingSyncContext(ctx.graphId, kind, id, target),
+        registration.type.schema
+      );
     };
     await ("transaction" in backend && backend.capabilities.transactions ? backend.transaction(async (tx) => hardDelete(tx)) : hardDelete(backend));
   });
@@ -13829,6 +13792,24 @@ function processPage(schema, rows) {
 }
 
 // src/store/search.ts
+function resolveSearchSlot(ctx, nodeKind, fieldPath) {
+  const nodeType = ctx.registry.getNodeType(nodeKind);
+  if (nodeType !== void 0) {
+    const fields = getEmbeddingFields(nodeType.schema);
+    const field2 = fields.find((entry2) => entry2.fieldPath === fieldPath);
+    if (field2 !== void 0) {
+      return {
+        dimensions: field2.dimensions,
+        metric: field2.metric,
+        indexType: field2.indexType
+      };
+    }
+  }
+  throw new ConfigurationError(
+    `Node kind "${nodeKind}" has no embedding field "${fieldPath}". Declare it with embedding(dimensions) on the node schema.`,
+    { capability: "vector", graphId: ctx.graphId }
+  );
+}
 async function executeFulltextSearch(ctx, nodeKind, options) {
   const { backend, graphId } = ctx;
   if (!backend.fulltextSearch) {
@@ -13890,12 +13871,29 @@ async function executeVectorSearch(ctx, nodeKind, options) {
     );
   }
   assertEfSearch(options.efSearch, "vectorSearch.efSearch");
+  const slot = resolveSearchSlot(ctx, nodeKind, options.fieldPath);
+  assertVectorQueryCompatible(
+    backend,
+    slot,
+    { metric: options.metric, queryEmbedding: options.queryEmbedding },
+    "vectorSearch"
+  );
+  assertMinScore(
+    options.minScore,
+    options.metric ?? slot.metric,
+    "vectorSearch.minScore"
+  );
   const rows = await backend.vectorSearch({
     graphId,
     nodeKind,
     fieldPath: options.fieldPath,
     queryEmbedding: options.queryEmbedding,
-    metric: options.metric ?? "cosine",
+    // Default to the field's DECLARED metric (the metric its index was built
+    // for); only an explicit caller override changes it. Defaulting to cosine
+    // here would mis-rank l2 / inner_product fields and bypass their ANN index.
+    metric: options.metric ?? slot.metric,
+    dimensions: slot.dimensions,
+    indexType: slot.indexType,
     limit: options.limit,
     ...options.minScore === void 0 ? {} : { minScore: options.minScore },
     ...options.efSearch === void 0 ? {} : { efSearch: options.efSearch }
@@ -13947,12 +13945,30 @@ async function executeHybridSearch(ctx, nodeKind, options) {
   const overFetchMultiplier = 4;
   const vectorK = options.vector.k ?? options.limit * overFetchMultiplier;
   const fulltextK = options.fulltext.k ?? options.limit * overFetchMultiplier;
+  const vectorSlot = resolveSearchSlot(ctx, nodeKind, options.vector.fieldPath);
+  assertVectorQueryCompatible(
+    backend,
+    vectorSlot,
+    {
+      metric: options.vector.metric,
+      queryEmbedding: options.vector.queryEmbedding
+    },
+    "hybridSearch.vector"
+  );
+  assertMinScore(
+    options.vector.minScore,
+    options.vector.metric ?? vectorSlot.metric,
+    "hybridSearch.vector.minScore"
+  );
   const vectorPromise = backend.vectorSearch({
     graphId,
     nodeKind,
     fieldPath: options.vector.fieldPath,
     queryEmbedding: options.vector.queryEmbedding,
-    metric: options.vector.metric ?? "cosine",
+    // Default to the field's declared metric (see executeVectorSearch).
+    metric: options.vector.metric ?? vectorSlot.metric,
+    dimensions: vectorSlot.dimensions,
+    indexType: vectorSlot.indexType,
     limit: vectorK,
     ...options.vector.minScore === void 0 ? {} : { minScore: options.vector.minScore },
     ...options.vector.efSearch === void 0 ? {} : { efSearch: options.vector.efSearch }
@@ -14043,6 +14059,30 @@ function assertEfSearch(efSearch, label) {
     );
   }
 }
+function assertMinScore(minScore, metric, label) {
+  if (minScore === void 0) return;
+  assertVectorMinScore(minScore, metric, label);
+}
+function assertVectorQueryCompatible(backend, slot, options, label) {
+  if (options.metric !== void 0 && options.metric !== slot.metric) {
+    throw new ConfigurationError(
+      `${label}: metric "${options.metric}" does not match the field's declared metric "${slot.metric}". Vector storage is built for the declared metric \u2014 omit metric or pass "${slot.metric}".`,
+      { backend: backend.dialect, capability: "vector" }
+    );
+  }
+  const supported = backend.capabilities.vector?.metrics;
+  if (supported !== void 0 && !supported.includes(slot.metric)) {
+    throw new ConfigurationError(
+      `${label}: backend "${backend.dialect}" does not support the "${slot.metric}" metric (supported: ${supported.join(", ")}).`,
+      { backend: backend.dialect, capability: "vector" }
+    );
+  }
+  if (options.queryEmbedding.length !== slot.dimensions) {
+    throw new RangeError(
+      `${label}: queryEmbedding has ${options.queryEmbedding.length} dimensions, but "${slot.dimensions}" are declared for this field.`
+    );
+  }
+}
 function validateFulltextCallOptions(backend, options) {
   const strategy = backend.fulltextStrategy;
   const capabilities = backend.capabilities.fulltext;
@@ -14149,7 +14189,11 @@ var StoreSearch = class {
   async fulltext(nodeKind, options) {
     this.#assertKindRegistered(nodeKind);
     return executeFulltextSearch(
-      { graphId: this.#context.graphId, backend: this.#context.backend },
+      {
+        graphId: this.#context.graphId,
+        backend: this.#context.backend,
+        registry: this.#context.registry
+      },
       nodeKind,
       options
     );
@@ -14168,7 +14212,11 @@ var StoreSearch = class {
   async vector(nodeKind, options) {
     this.#assertKindRegistered(nodeKind);
     return executeVectorSearch(
-      { graphId: this.#context.graphId, backend: this.#context.backend },
+      {
+        graphId: this.#context.graphId,
+        backend: this.#context.backend,
+        registry: this.#context.registry
+      },
       nodeKind,
       options
     );
@@ -14185,7 +14233,11 @@ var StoreSearch = class {
   async hybrid(nodeKind, options) {
     this.#assertKindRegistered(nodeKind);
     return executeHybridSearch(
-      { graphId: this.#context.graphId, backend: this.#context.backend },
+      {
+        graphId: this.#context.graphId,
+        backend: this.#context.backend,
+        registry: this.#context.registry
+      },
       nodeKind,
       options
     );
@@ -14234,6 +14286,7 @@ var UNKNOWN_SCHEMA_METADATA = Object.freeze({
   schemaVersion: void 0,
   schemaHash: void 0
 });
+var DEFAULT_REEMBED_BATCH_SIZE = 200;
 var CAUGHT_UP_VERB_DETAILS = {
   evolve: { phrase: "evolve", code: "EVOLVE_BEFORE_INITIALIZE" },
   materialize: {
@@ -14248,6 +14301,10 @@ var CAUGHT_UP_VERB_DETAILS = {
   undeprecate: {
     phrase: "undeprecate kinds on",
     code: "DEPRECATE_BEFORE_INITIALIZE"
+  },
+  reembed: {
+    phrase: "re-embed a vector field on",
+    code: "REEMBED_BEFORE_INITIALIZE"
   }
 };
 var Store = class _Store {
@@ -14799,7 +14856,7 @@ var Store = class _Store {
       return fn({ nodes: this.nodes, edges: this.edges });
     }
     return this.#backend.transaction(
-      async (txBackend, sql17) => fn(this.#buildTransactionContext(txBackend, sql17))
+      async (txBackend, sql18) => fn(this.#buildTransactionContext(txBackend, sql18))
     );
   }
   /**
@@ -14876,7 +14933,7 @@ var Store = class _Store {
    * raw Drizzle handle bound to the same transaction (#140);
    * `undefined` only on the non-transactional fallback.
    */
-  #buildTransactionContext(txBackend, sql17) {
+  #buildTransactionContext(txBackend, sql18) {
     const txNodeOperations = {
       ...this.#nodeOperations,
       createQuery: () => this.#createQueryForBackend(txBackend)
@@ -14899,7 +14956,7 @@ var Store = class _Store {
       txBackend,
       txEdgeOperations
     );
-    return sql17 === void 0 ? { nodes, edges } : { nodes, edges, sql: sql17 };
+    return sql18 === void 0 ? { nodes, edges } : { nodes, edges, sql: sql18 };
   }
   // === Graph Lifecycle ===
   /**
@@ -14916,11 +14973,44 @@ var Store = class _Store {
       await target.clearGraph(this.graphId);
     };
     await (this.#backend.capabilities.transactions ? this.#backend.transaction(async (tx) => doClear(tx)) : doClear(this.#backend));
+    await this.#clearVectorStorage();
     this.#nodeCollections = void 0;
     this.#edgeCollections = void 0;
     this.#algorithms = void 0;
     this.#search = void 0;
   }
+  /**
+   * Resets every declared embedding field's per-field storage for this graph by
+   * dropping and recreating it empty. Drop+recreate (rather than DELETE) mirrors
+   * `reembedVectorField` and keeps the backend's storage-ensure latch valid: the
+   * table still exists after clear, so a later write finds it. Enumerated from
+   * the in-memory registry (not the DB schema, which `clearGraph` just wiped).
+   */
+  async #clearVectorStorage() {
+    const backend = this.#backend;
+    const strategy = backend.vectorStrategy;
+    if (strategy === void 0 || backend.executeDdl === void 0) return;
+    for (const [nodeKind, nodeType] of this.#registry.nodeKinds) {
+      for (const field2 of resolveEmbeddingFields(nodeType.schema)) {
+        const slot = {
+          graphId: this.graphId,
+          nodeKind,
+          fieldPath: field2.fieldPath,
+          dimensions: field2.dimensions,
+          metric: field2.metric,
+          indexType: field2.indexType
+        };
+        for (const ddl of strategy.buildDropStorage(slot)) {
+          await backend.executeDdl(ddl);
+        }
+        for (const contribution of strategy.ownedTables(slot)) {
+          for (const ddl of contribution.createDdl) {
+            await backend.executeDdl(ddl);
+          }
+        }
+      }
+    }
+  }
   // === Lifecycle ===
   /**
    * Refreshes the backend's query-planner statistics.
@@ -15144,6 +15234,150 @@ var Store = class _Store {
       options ?? {}
     );
   }
+  /**
+   * Recreate a vector field's per-field storage at its current declared
+   * dimension, then optionally re-embed existing rows.
+   *
+   * Use this after changing a field's `embedding(N)` to `embedding(M)` (e.g. a
+   * new embedding model): the stored N-dim vectors are invalid under the new
+   * dimension and must be recomputed, not converted. This drops and recreates
+   * the per-`(graphId, kind, field)` table at the new dimension — a brief
+   * window where the field returns no vector hits — resets its materialization
+   * marker, then, when `options.embed` is supplied, pages the kind's nodes,
+   * calls `embed(batch)`, and upserts the returned vectors. Without `embed`,
+   * storage is recreated empty and the caller re-embeds via normal
+   * `update()` / `upsertEmbedding` writes.
+   *
+   * @throws {ConfigurationError} when the backend has no vector strategy or
+   *   cannot execute DDL, or `(kind, fieldPath)` is not a declared embedding.
+   */
+  async reembedVectorField(kind, fieldPath, options) {
+    if (options?.batchSize !== void 0 && (!Number.isInteger(options.batchSize) || options.batchSize <= 0)) {
+      throw new RangeError(
+        `reembedVectorField batchSize must be a positive integer, got: ${options.batchSize}`
+      );
+    }
+    const { activeRow, baseline } = await this.#loadCaughtUp("reembed");
+    const backend = this.#backend;
+    const strategy = backend.vectorStrategy;
+    if (strategy === void 0 || backend.executeDdl === void 0) {
+      throw new ConfigurationError(
+        "reembedVectorField requires a backend with a vector strategy and executeDdl.",
+        {
+          backend: backend.dialect,
+          capability: "vector",
+          operation: "reembed"
+        }
+      );
+    }
+    const declaration = (baseline.indexes ?? []).find(
+      (candidate) => candidate.entity === "vector" && candidate.kind === kind && candidate.fieldPath === fieldPath
+    );
+    if (declaration === void 0) {
+      throw new ConfigurationError(
+        `No embedding field "${kind}.${fieldPath}" is declared in the active schema.`,
+        { kind, fieldPath, operation: "reembed" }
+      );
+    }
+    const slot = {
+      graphId: this.graphId,
+      nodeKind: kind,
+      fieldPath,
+      dimensions: declaration.dimensions,
+      metric: declaration.metric,
+      indexType: declaration.indexType
+    };
+    for (const ddl of strategy.buildDropStorage(slot)) {
+      await backend.executeDdl(ddl);
+    }
+    for (const contribution of strategy.ownedTables(slot)) {
+      for (const ddl of contribution.createDdl) {
+        await backend.executeDdl(ddl);
+      }
+    }
+    const declaredIndexMaterializes = declaration.indexType !== "none" && backend.capabilities.vector?.indexTypes.includes(
+      declaration.indexType
+    ) === true;
+    if (declaredIndexMaterializes && backend.createVectorIndex !== void 0) {
+      await backend.createVectorIndex({
+        graphId: this.graphId,
+        nodeKind: kind,
+        fieldPath,
+        dimensions: declaration.dimensions,
+        metric: declaration.metric,
+        indexType: declaration.indexType,
+        indexParams: {
+          m: declaration.indexParams.m,
+          efConstruction: declaration.indexParams.efConstruction,
+          ...declaration.indexParams.lists === void 0 ? {} : { lists: declaration.indexParams.lists }
+        }
+      });
+    }
+    if (declaredIndexMaterializes && backend.recordIndexMaterialization !== void 0) {
+      const tableName = strategy.tableName(this.graphId, kind, fieldPath);
+      const signature = await computeIndexSignature(
+        backend.dialect,
+        tableName,
+        declaration
+      );
+      const now = nowIso();
+      await backend.recordIndexMaterialization({
+        indexName: vectorStatusKey(this.graphId, declaration.name),
+        graphId: this.graphId,
+        entity: "vector",
+        kind,
+        signature,
+        schemaVersion: activeRow.version,
+        attemptedAt: now,
+        materializedAt: now,
+        error: void 0
+      });
+    }
+    if (options?.embed === void 0) {
+      return { recreated: true, reembedded: 0 };
+    }
+    if (backend.upsertEmbedding === void 0) {
+      throw new ConfigurationError(
+        "reembedVectorField with an `embed` callback requires a backend that supports upsertEmbedding.",
+        {
+          backend: backend.dialect,
+          capability: "vector",
+          operation: "reembed"
+        }
+      );
+    }
+    const upsertEmbedding = backend.upsertEmbedding;
+    const batchSize = options.batchSize ?? DEFAULT_REEMBED_BATCH_SIZE;
+    const collection = this.getNodeCollectionOrThrow(kind);
+    let reembedded = 0;
+    let offset = 0;
+    for (; ; ) {
+      const batch = await collection.find({
+        limit: batchSize,
+        offset
+      });
+      if (batch.length === 0) break;
+      const vectors = await options.embed(batch);
+      for (const node of batch) {
+        const embedding2 = vectors.get(node.id);
+        if (embedding2 === void 0) continue;
+        await upsertEmbedding({
+          graphId: this.graphId,
+          nodeKind: kind,
+          nodeId: node.id,
+          fieldPath,
+          embedding: embedding2,
+          dimensions: declaration.dimensions,
+          metric: declaration.metric,
+          indexType: declaration.indexType
+        });
+        reembedded += 1;
+      }
+      offset += batch.length;
+      if (batch.length < batchSize) break;
+    }
+    return { recreated: true, reembedded };
+  }
   /**
    * Removes extension kinds from the schema with cascading edge and
    * ontology cleanup. Two-phase by design:
@@ -15521,6 +15755,6 @@ async function createVerifiedStore(graph, backend, options) {
   return [store, result];
 }
 
-export { DEFAULT_SQL_SCHEMA, ExecutableAggregateQuery, ExecutableQuery, MAX_EXPLICIT_RECURSIVE_DEPTH, MAX_RECURSIVE_DEPTH, PreparedQuery, QueryBuilder, StoreSearch, UnionableQuery, avg, composeFragments, count, countDistinct, countDistinctEdges, countEdges, createExternalRef, createFragment, createQueryBuilder, createSqlSchema, createStore, createStoreWithSchema, createVerifiedStore, defineSubgraphProject, exists, externalRef, field, fieldRef, generateId, getExternalRefTable, having, havingEq, havingGt, havingGte, havingLt, havingLte, inSubquery, isExternalRefSchema, isParameterRef, limitFragment, max, metaEdge, min, notExists, notInSubquery, offsetFragment, orderByFragment, param, sum };
+export { DEFAULT_SQL_SCHEMA, ExecutableAggregateQuery, ExecutableQuery, MAX_EXPLICIT_RECURSIVE_DEPTH, MAX_RECURSIVE_DEPTH, PreparedQuery, QueryBuilder, StoreSearch, UnionableQuery, avg, composeFragments, count, countDistinct, countDistinctEdges, countEdges, createExternalRef, createFragment, createQueryBuilder, createSqlSchema, createStore, createStoreWithSchema, createVerifiedStore, defineSubgraphProject, exists, externalRef, field, fieldRef, generateId, getExternalRefTable, having, havingEq, havingGt, havingGte, havingLt, havingLte, inSubquery, isExternalRefSchema, isParameterRef, limitFragment, max, metaEdge, migrateLegacyEmbeddings, min, notExists, notInSubquery, offsetFragment, orderByFragment, param, sum };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map