@nicia-ai/typegraph 0.28.1 → 0.29.0

package/dist/{store-Ufc1Eoey.d.ts → store-De0Y33wP.d.ts}

@@ -1,9 +1,9 @@
 import { z } from 'zod';
-import { p as SqlDialect, ah as SqlSchema, F as FulltextStrategy, ax as ValueType, ay as PredicateExpression, az as VectorMetricType, a0 as FulltextQueryMode, Q as QueryAst, J as JsonPointer, L as FieldRef, ac as ParameterRef, G as GraphBackend, al as TransactionBackend, a5 as JsonPointerInput, am as TraversalExpansion, aA as Traversal, aB as NodePredicate, aC as ProjectedField, ab as OrderSpec, aD as GroupBySpec, a3 as HybridFusionOptions, aE as RecursiveCyclePolicy, aF as TraversalDirection$1, aG as EdgeRow, aH as NodeRow, U as AdoptedTransaction, K as AggregateExpr, aI as SelectiveField, aJ as ComposableQuery, aK as SetOperationType, aL as SetOperation, ag as SortDirection, m as JsonSchema, aM as VectorMetric } from './types-CQ7xXJMP.js';
-import { K as KindRegistry, G as GraphDef, u as EdgeKinds, x as NodeKinds, t as AllNodeTypes, c as SchemaManagerOptions, d as SchemaValidationResult } from './manager-ehLTTNq0.js';
-import { A as AnyEdgeType, N as NodeType, T as TemporalMode, e as EdgeType, E as EdgeRegistration, h as EdgeId, m as NodeId, b as NodeRegistration, K as KindEntity, f as Cardinality, k as EndpointExistence, d as KindAnnotations, o as UniquenessScope, g as Collation, G as GraphExtension } from './extension-types-B78CZfA5.js';
+import { p as SqlDialect, ai as SqlSchema, F as FulltextStrategy, V as VectorStrategy, aA as VectorSlotMap, aB as ValueType, aC as PredicateExpression, aD as VectorMetricType, a1 as FulltextQueryMode, Q as QueryAst, J as JsonPointer, P as FieldRef, ad as ParameterRef, G as GraphBackend, am as TransactionBackend, a6 as JsonPointerInput, an as TraversalExpansion, aE as Traversal, aF as NodePredicate, aG as ProjectedField, ac as OrderSpec, aH as GroupBySpec, a4 as HybridFusionOptions, aI as RecursiveCyclePolicy, aJ as TraversalDirection$1, aK as EdgeRow, aL as NodeRow, W as AdoptedTransaction, L as AggregateExpr, aM as SelectiveField, aN as ComposableQuery, aO as SetOperationType, aP as SetOperation, ah as SortDirection, m as JsonSchema, aQ as VectorMetric } from './types-CmAT-Z47.js';
+import { K as KindRegistry, G as GraphDef, u as EdgeKinds, x as NodeKinds, t as AllNodeTypes, c as SchemaManagerOptions, d as SchemaValidationResult } from './manager-BUugwCYz.js';
+import { A as AnyEdgeType, N as NodeType, T as TemporalMode, d as EdgeType, E as EdgeRegistration, i as EdgeId, m as NodeId, b as NodeRegistration, K as KindEntity, f as Cardinality, g as EndpointExistence, e as KindAnnotations, U as UniquenessScope, C as Collation, G as GraphExtension } from './extension-types-CwHV-Uk4.js';
 import { SQL } from 'drizzle-orm';
-import { b as MaterializeIndexesOptions, M as MaterializeIndexesResult } from './materialize-indexes-DFavFQah.js';
+import { b as MaterializeIndexesOptions, M as MaterializeIndexesResult } from './materialize-indexes-lkawaDor.js';
 
 /**
  * Embedding type for vector search.
@@ -239,6 +239,20 @@ type CompileQueryOptions = Readonly<{
      * default (tsvector).
      */
     fulltextStrategy?: FulltextStrategy | undefined;
+    /**
+     * Vector strategy override. When set, `field.similarTo(...)`
+     * predicates compile against the strategy's per-`(kind, field)`
+     * tables and distance expression. Callers read it from
+     * `backend.vectorStrategy` so a backend-declared strategy (pgvector,
+     * libsql-native, sqlite-vec) drives the per-field relevance scan.
+     */
+    vectorStrategy?: VectorStrategy | undefined;
+    /**
+     * Declared embedding slots `(kind, fieldPath) -> descriptor` used by
+     * the `field.similarTo(...)` CTE to know which kinds in an alias
+     * declare the field. Callers build it from the graph's node schemas.
+     */
+    vectorSlots?: VectorSlotMap | undefined;
 }>;
 
 type FieldTypeInfo = Readonly<{
@@ -1920,8 +1934,29 @@ type MaterializeRemovalsEntry = Readonly<{
     status: "removed" | "failed";
     error?: Error;
 }>;
+/**
+ * Outcome of reclaiming one per-`(graphId, kind, field)` vector table that
+ * was orphaned when its embedding field was dropped from a *surviving*
+ * kind's schema. Distinct from {@link MaterializeRemovalsEntry} (whole
+ * kinds) because the unit is a single embedding field, not a kind.
+ */
+type ReclaimedVectorFieldEntry = Readonly<{
+    kind: string;
+    fieldPath: string;
+    status: "reclaimed" | "failed";
+    error?: Error;
+}>;
 type MaterializeRemovalsResult = Readonly<{
     results: readonly MaterializeRemovalsEntry[];
+    /**
+     * Embedding fields removed from a *surviving* kind whose per-field vector
+     * table this pass dropped (or confirmed already absent). Empty when the
+     * backend has no vector strategy or no embedding field has ever been
+     * dropped. Re-derived from immutable schema history each call, so it lists
+     * the same removed fields on repeat passes — the underlying drop is
+     * idempotent (`DROP ... IF EXISTS`). See {@link reclaimRemovedVectorFieldTables}.
+     */
+    reclaimedVectorFields: readonly ReclaimedVectorFieldEntry[];
 }>;
 
 /**
@@ -3147,6 +3182,32 @@ type StoreSchemaMetadata = Readonly<{
  *   .execute();
  * ```
  */
+/**
+ * Optional embedder for {@link Store.reembedVectorField}. Receives a batch of
+ * the kind's nodes and returns a map of `nodeId → new embedding vector` (omit
+ * an id to leave that node without an embedding). Called once per page; the
+ * page size is `batchSize`.
+ */
+type ReembedFunction = (nodes: readonly Node[]) => Promise<ReadonlyMap<string, readonly number[]>> | ReadonlyMap<string, readonly number[]>;
+/** Options for {@link Store.reembedVectorField}. */
+type ReembedVectorFieldOptions = Readonly<{
+    /**
+     * When supplied, drives a batched re-embed loop after recreating storage:
+     * pages the kind's nodes, calls `embed(batch)`, and upserts the returned
+     * vectors. When omitted, storage is recreated empty and the caller
+     * re-embeds via normal `update()` / `upsertEmbedding` writes.
+     */
+    embed?: ReembedFunction;
+    /** Re-embed page size. Default 200. */
+    batchSize?: number;
+}>;
+/** Result of {@link Store.reembedVectorField}. */
+type ReembedVectorFieldResult = Readonly<{
+    /** Whether the per-field storage was dropped and recreated. */
+    recreated: boolean;
+    /** Number of nodes whose embedding was re-written (0 without `embed`). */
+    reembedded: number;
+}>;
 declare class Store<G extends GraphDef> {
     #private;
     constructor(graph: G, backend: GraphBackend, options?: StoreOptions, schemaMetadata?: StoreSchemaMetadata);
@@ -3680,6 +3741,24 @@ declare class Store<G extends GraphDef> {
      *   has no schema yet.
      */
     materializeIndexes(options?: MaterializeIndexesOptions): Promise<MaterializeIndexesResult>;
+    /**
+     * 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.
+     */
+    reembedVectorField(kind: string, fieldPath: string, options?: ReembedVectorFieldOptions): Promise<ReembedVectorFieldResult>;
     /**
      * Removes extension kinds from the schema with cascading edge and
      * ontology cleanup. Two-phase by design:
@@ -3833,4 +3912,4 @@ declare function createStoreWithSchema<G extends GraphDef>(graph: G, backend: Gr
  */
 declare function createVerifiedStore<G extends GraphDef>(graph: G, backend: GraphBackend, options?: StoreOptions): Promise<[Store<G>, SchemaValidationResult]>;
 
-export { type MaterializeRemovalsOptions as $, type AliasMap as A, type BaseTraversalOptions as B, type CreateQueryBuilderOptions as C, DEFAULT_SEARCHABLE_LANGUAGE as D, type EdgeAliasMap as E, type EmbeddingSchema as F, type EmbeddingValue as G, ExecutableAggregateQuery as H, ExecutableQuery as I, type FieldAccessor as J, type FulltextSearchHit as K, type FulltextSearchOptions as L, type GetOrCreateAction as M, type GraphAlgorithms as N, type GraphEdgeCollections as O, type GraphNodeCollections as P, QueryBuilder as Q, type HookContext as R, Store as S, TraversalBuilder as T, type HybridFulltextOptions as U, type HybridSearchHit as V, type HybridSearchOptions as W, type HybridVectorOptions as X, type IfExistsMode as Y, type KindIntrospection as Z, type MaterializeRemovalsEntry as _, type AggregateResult as a, getEmbeddingDimensions as a$, type MaterializeRemovalsResult as a0, type NeighborsOptions as a1, type Node as a2, type NodeAccessor as a3, type NodeAlias as a4, type NodeCollection as a5, type NodeGetOrCreateByConstraintOptions as a6, type NodeGetOrCreateByConstraintResult as a7, type NodeIdentifier as a8, type NodeRef as a9, type StoreProjection as aA, type StoreRef as aB, StoreSearch as aC, type StreamOptions as aD, type SubgraphEdgeResult as aE, type SubgraphNodeResult as aF, type SubgraphOptions as aG, type SubgraphResult as aH, type SubsetEdge as aI, type SubsetNode as aJ, type TemporalAlgorithmOptions as aK, type TransactionContext as aL, type TraversalDirection as aM, type TypedEdgeCollection as aN, UnionableQuery as aO, type UniqueIntrospection as aP, type UpdateEdgeInput as aQ, type UpdateNodeInput as aR, type VectorSearchHit as aS, type VectorSearchOptions as aT, createStore as aU, createStoreWithSchema as aV, createVerifiedStore as aW, defineSubgraphProject as aX, embedding as aY, exists as aZ, fieldRef as a_, type OntologyIntrospection as aa, type OperationHookContext as ab, type PaginateOptions as ac, type PaginatedResult as ad, type PathNode as ae, type Predicate as af, PreparedQuery as ag, type PropsAccessor as ah, type QueryHookContext as ai, type QueryOptions as aj, type ReachableNode as ak, type ReachableOptions as al, type RebuildFulltextOptions as am, type RebuildFulltextResult as an, type RecursiveTraversalOptions as ao, type SchemaIntrospection as ap, type SearchableMetadata as aq, type SearchableOptions as ar, type SearchableSchema as as, type SelectContext as at, type SelectableEdge as au, type SelectableNode as av, type ShortestPathOptions as aw, type ShortestPathResult as ax, type StoreHooks as ay, type StoreOptions as az, type AlgorithmCyclePolicy as b, getSearchableMetadata as b0, inSubquery as b1, isEmbeddingSchema as b2, isParameterRef as b3, isSearchableSchema as b4, notExists as b5, notInSubquery as b6, param as b7, searchable as b8, type AnyEdge as c, type AnyNode as d, type BatchResults as e, type BatchableQuery as f, type ConstraintNames as g, type CreateEdgeInput as h, type CreateNodeInput as i, type DegreeOptions as j, type DynamicEdgeAccessor as k, type DynamicEdgeCollection as l, type DynamicEdgeType as m, type DynamicFieldBuilder as n, type DynamicNodeAccessor as o, type DynamicNodeCollection as p, type DynamicNodeType as q, type DynamicSelectableEdge as r, type DynamicSelectableNode as s, type Edge as t, type EdgeAccessor as u, type EdgeCollection as v, type EdgeFindByEndpointsOptions as w, type EdgeGetOrCreateByEndpointsOptions as x, type EdgeGetOrCreateByEndpointsResult as y, type EdgeIntrospection as z };
+export { type KindIntrospection as $, type AliasMap as A, type BaseTraversalOptions as B, type CreateQueryBuilderOptions as C, DEFAULT_SEARCHABLE_LANGUAGE as D, type EmbeddingMetric as E, type EdgeGetOrCreateByEndpointsResult as F, type EdgeIntrospection as G, type EmbeddingSchema as H, type EmbeddingValue as I, ExecutableAggregateQuery as J, ExecutableQuery as K, type FieldAccessor as L, type FulltextSearchHit as M, type FulltextSearchOptions as N, type GetOrCreateAction as O, type GraphAlgorithms as P, QueryBuilder as Q, type GraphEdgeCollections as R, Store as S, TraversalBuilder as T, type GraphNodeCollections as U, type HookContext as V, type HybridFulltextOptions as W, type HybridSearchHit as X, type HybridSearchOptions as Y, type HybridVectorOptions as Z, type IfExistsMode as _, type EmbeddingIndexType as a, createStoreWithSchema as a$, type MaterializeRemovalsEntry as a0, type MaterializeRemovalsOptions as a1, type MaterializeRemovalsResult as a2, type NeighborsOptions as a3, type Node as a4, type NodeAccessor as a5, type NodeAlias as a6, type NodeCollection as a7, type NodeGetOrCreateByConstraintOptions as a8, type NodeGetOrCreateByConstraintResult as a9, type SelectableEdge as aA, type SelectableNode as aB, type ShortestPathOptions as aC, type ShortestPathResult as aD, type StoreHooks as aE, type StoreOptions as aF, type StoreProjection as aG, type StoreRef as aH, StoreSearch as aI, type StreamOptions as aJ, type SubgraphEdgeResult as aK, type SubgraphNodeResult as aL, type SubgraphOptions as aM, type SubgraphResult as aN, type SubsetEdge as aO, type SubsetNode as aP, type TemporalAlgorithmOptions as aQ, type TransactionContext as aR, type TraversalDirection as aS, type TypedEdgeCollection as aT, UnionableQuery as aU, type UniqueIntrospection as aV, type UpdateEdgeInput as aW, type UpdateNodeInput as aX, type VectorSearchHit as aY, type VectorSearchOptions as aZ, createStore as a_, type NodeIdentifier as aa, type NodeRef as ab, type OntologyIntrospection as ac, type OperationHookContext as ad, type PaginateOptions as ae, type PaginatedResult as af, type PathNode as ag, type Predicate as ah, PreparedQuery as ai, type PropsAccessor as aj, type QueryHookContext as ak, type QueryOptions as al, type ReachableNode as am, type ReachableOptions as an, type RebuildFulltextOptions as ao, type RebuildFulltextResult as ap, type ReclaimedVectorFieldEntry as aq, type RecursiveTraversalOptions as ar, type ReembedFunction as as, type ReembedVectorFieldOptions as at, type ReembedVectorFieldResult as au, type SchemaIntrospection as av, type SearchableMetadata as aw, type SearchableOptions as ax, type SearchableSchema as ay, type SelectContext as az, type EdgeAliasMap as b, createVerifiedStore as b0, defineSubgraphProject as b1, embedding as b2, exists as b3, fieldRef as b4, getEmbeddingDimensions as b5, getSearchableMetadata as b6, inSubquery as b7, isEmbeddingSchema as b8, isParameterRef as b9, isSearchableSchema as ba, notExists as bb, notInSubquery as bc, param as bd, searchable as be, type AggregateResult as c, type AlgorithmCyclePolicy as d, type AnyEdge as e, type AnyNode as f, type BatchResults as g, type BatchableQuery as h, type ConstraintNames as i, type CreateEdgeInput as j, type CreateNodeInput as k, type DegreeOptions as l, type DynamicEdgeAccessor as m, type DynamicEdgeCollection as n, type DynamicEdgeType as o, type DynamicFieldBuilder as p, type DynamicNodeAccessor as q, type DynamicNodeCollection as r, type DynamicNodeType as s, type DynamicSelectableEdge as t, type DynamicSelectableNode as u, type Edge as v, type EdgeAccessor as w, type EdgeCollection as x, type EdgeFindByEndpointsOptions as y, type EdgeGetOrCreateByEndpointsOptions as z };

package/dist/{types-B-sJJ4GQ.d.ts → types-B5GSeE3t.d.ts}

@@ -1,5 +1,5 @@
-import { K as KindEntity } from './extension-types-B78CZfA5.js';
-import { J as JsonPointer } from './types-CQ7xXJMP.js';
+import { K as KindEntity } from './extension-types-CwHV-Uk4.js';
+import { J as JsonPointer } from './types-CmAT-Z47.js';
 
 /**
  * QueryProfiler types.

package/dist/{types-CmUA9sal.d.cts → types-Bwlp_yvu.d.cts}

@@ -1,5 +1,5 @@
-import { K as KindEntity } from './extension-types-B78CZfA5.cjs';
-import { J as JsonPointer } from './types-CMQymcwk.cjs';
+import { K as KindEntity } from './extension-types-CwHV-Uk4.cjs';
+import { J as JsonPointer } from './types-DXCSyxac.cjs';
 
 /**
  * QueryProfiler types.

package/dist/{types-CMQymcwk.d.cts → types-CmAT-Z47.d.ts}

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { N as NodeType, e as EdgeType, o as UniquenessScope, g as Collation, D as DeleteBehavior, d as KindAnnotations, f as Cardinality, k as EndpointExistence, T as TemporalMode, G as GraphExtension, I as IndexEntity, K as KindEntity, a as NullCheckOp, A as AnyEdgeType } from './extension-types-B78CZfA5.cjs';
+import { N as NodeType, d as EdgeType, U as UniquenessScope, C as Collation, D as DeleteBehavior, e as KindAnnotations, f as Cardinality, g as EndpointExistence, T as TemporalMode, G as GraphExtension, I as IndexEntity, K as KindEntity, a as NullCheckOp, A as AnyEdgeType } from './extension-types-CwHV-Uk4.js';
 import { SQL } from 'drizzle-orm';
 import { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
 import { BaseSQLiteDatabase } from 'drizzle-orm/sqlite-core';
@@ -120,8 +120,6 @@ type SqlTableNames = Readonly<{
     nodes: string;
     /** Edges table name (default: "typegraph_edges") */
     edges: string;
-    /** Node embeddings table name (default: "typegraph_node_embeddings") */
-    embeddings: string;
     /** Node fulltext table name (default: "typegraph_node_fulltext") */
     fulltext: string;
     /** Node uniques table name (default: "typegraph_node_uniques") */
@@ -138,8 +136,6 @@ type SqlSchema = Readonly<{
     nodesTable: SQL;
     /** Get a SQL reference to the edges table */
     edgesTable: SQL;
-    /** Get a SQL reference to the embeddings table */
-    embeddingsTable: SQL;
     /** Get a SQL reference to the fulltext table */
     fulltextTable: SQL;
 }>;
@@ -162,7 +158,7 @@ type SqlSchema = Readonly<{
  * const schema = createSqlSchema({
  *   nodes: "myapp_nodes",
  *   edges: "myapp_edges",
- *   embeddings: "myapp_embeddings",
+ *   fulltext: "myapp_fulltext",
  * });
  * ```
  */
@@ -171,6 +167,27 @@ declare function createSqlSchema(names?: Partial<SqlTableNames>): SqlSchema;
  * Default SqlSchema using standard TypeGraph table names.
  */
 declare const DEFAULT_SQL_SCHEMA: SqlSchema;
+/**
+ * The compiler's resolved view of one declared embedding field — the
+ * `(dimensions, metric, indexType)` a {@link VectorStrategy} needs to
+ * name and scan the field's typed per-`(kind, field)` storage. Sourced
+ * from the registered node schema's `embedding()` declaration when the
+ * store builds its compile options.
+ */
+type VectorSlotDescriptor = Readonly<{
+    dimensions: number;
+    metric: VectorMetric;
+    indexType: VectorIndexType;
+}>;
+/**
+ * Map of declared embedding slots keyed by {@link vectorSlotKey} -
+ * `"<nodeKind>\0<fieldPath>"` (NUL-separated). Carries every `(concrete kind,
+ * fieldPath)` that declares an embedding field, so the compiler's
+ * `field.similarTo(...)` CTE can UNION ALL the per-field tables for the
+ * kinds in an alias that actually declare the field (only
+ * `includeSubClasses` yields more than one).
+ */
+type VectorSlotMap = ReadonlyMap<string, VectorSlotDescriptor>;
 
 /**
  * A single table TypeGraph owns.
@@ -348,6 +365,181 @@ interface FulltextStrategy {
 declare const tsvectorStrategy: FulltextStrategy;
 declare const fts5Strategy: FulltextStrategy;
 
+/**
+ * Vector Strategy — pluggable storage + SQL generation for a backend's
+ * vector stack. The sibling of {@link FulltextStrategy}: a strategy owns
+ * every statement that touches its embedding storage — the per-field DDL,
+ * upsert, delete, similarity search, and (optional) ANN index lifecycle —
+ * plus the capability advertisement and the distance/score expressions the
+ * query compiler splices into its relevance CTE.
+ *
+ * ## Why a strategy, and why per-(kind, field) storage
+ *
+ * The spike behind #157 established that "real" ANN on every engine we
+ * support converges on a
+ * **typed, fixed-dimension structure per `(nodeKind, fieldPath)`**:
+ *
+ * - pgvector: a `vector(N)` column + HNSW/IVFFlat;
+ * - libSQL native: an `F32_BLOB(N)` column + `libsql_vector_idx` +
+ *   `vector_top_k` (a plain `BLOB` or dimensionless `F32_BLOB` is rejected
+ *   by the index — the dimension must live in the column type);
+ * - sqlite-vec: a `vec0(embedding float[N])` virtual table.
+ *
+ * The legacy single shared `typegraph_node_embeddings` table (one generic
+ * column holding mixed-dimension vectors) can only ever be brute-forced;
+ * pgvector was the sole engine that hid this, because its index supplies the
+ * dimension via a `::vector(N)` cast expression. So storage is the
+ * strategy's to own, slot by slot, rather than a fixed global table.
+ *
+ * Brute force remains a legitimate, capability-advertised mode (libSQL's
+ * `vector_distance_cos` over a column with no index, sqlite-vec's
+ * `vec_distance_cosine`): a strategy whose `capabilities.indexTypes` is
+ * `["none"]` simply never emits an ANN index and `buildSearch` always scans.
+ */
+
+/**
+ * The resolved identity of one embedding field's storage in a graph —
+ * everything a strategy needs to DDL, address, and index it.
+ *
+ * Graph-scoped: each `(graphId, nodeKind, fieldPath)` gets its own physical
+ * table. TypeGraph supports many graphs per physical database, and the same
+ * `(kind, field)` can carry different embedding dimensions across graphs — a
+ * shared per-`(kind, field)` table would collide on the fixed column type
+ * (`vector(N)` / `F32_BLOB(N)`). Graph-scoping also makes libSQL's
+ * table-global `vector_top_k` per-graph-exact (no cross-graph recall bleed).
+ */
+type VectorSlot = Readonly<{
+    /** Graph the embedding belongs to — scopes the physical table. */
+    graphId: string;
+    /** Node kind owning the embedding field (e.g. `"Document"`). */
+    nodeKind: string;
+    /** Dot-path of the embedding field within the node props (e.g. `"embedding"`). */
+    fieldPath: string;
+    /** Fixed vector dimension `N` for this field — carried into the column type. */
+    dimensions: number;
+    /** Distance metric the field's index is built for. */
+    metric: VectorMetric;
+    /**
+     * Index type to materialize. `"none"` means brute-force only (no ANN
+     * index emitted); the strategy still stores and searches the field.
+     */
+    indexType: VectorIndexType;
+    /**
+     * Optional ANN index tuning carried into the index DDL (pgvector
+     * `m`/`ef_construction`/`lists`). Present on the create-index / re-embed
+     * paths (resolved from the field's `embedding()` declaration); omitted on
+     * the write/search ensure paths, where the strategy falls back to defaults.
+     */
+    indexParams?: Readonly<{
+        m?: number;
+        efConstruction?: number;
+        lists?: number;
+    }>;
+}>;
+/**
+ * Derives the `VectorCapabilities` a backend advertises from its active
+ * strategy, so the two never drift (mirrors `buildFulltextCapabilities`).
+ * The strategy is the single source of truth; there are no per-call-site
+ * `SQLITE_VECTOR_*` constants.
+ */
+declare function buildVectorCapabilities(strategy: VectorStrategy): VectorCapabilities;
+/**
+ * A pluggable vector implementation. Each strategy is self-contained:
+ * given a {@link VectorSlot}, it emits every statement the backend and
+ * compiler need — per-field storage DDL, writes, similarity search, ANN
+ * index lifecycle — and advertises exactly the metrics and index types it
+ * can honor. Adding the Nth backend is one of these objects; no core edits.
+ */
+interface VectorStrategy {
+    /** Human-readable identifier used in error messages and telemetry. */
+    readonly name: string;
+    /**
+     * The metrics, index types, and dimension ceiling this strategy honors —
+     * advertised verbatim as `backend.capabilities.vector`. Asymmetry across
+     * engines is legitimate and explicit here (pgvector has `inner_product`;
+     * libSQL/sqlite-vec do not), never a silent runtime failure.
+     */
+    readonly capabilities: VectorCapabilities;
+    /**
+     * Deterministic physical table (or virtual-table) name backing a field in
+     * a graph. The compiler references this to scan the right per-field storage,
+     * and the backend uses it to route upserts/deletes. Must be a stable,
+     * collision-safe SQL identifier derived from `(graphId, nodeKind, fieldPath)`.
+     */
+    tableName(graphId: string, nodeKind: string, fieldPath: string): string;
+    /**
+     * The per-field storage this strategy owns for `slot`, as Drizzle-free
+     * `StrategyTableContribution`s (resolved `tableName`, deterministic
+     * idempotent `createDdl` for the table **and** its ANN index when the
+     * slot's `indexType` warrants one, `runtimeEnsure`). Rides the #129/#135
+     * table-contribution + durable-materialization machinery exactly as the
+     * FTS5 / tsvector virtual tables do — these are materialized per graph by
+     * `materializeIndexes()`, not by global `bootstrapTables`.
+     */
+    ownedTables(slot: VectorSlot): readonly StrategyTableContribution[];
+    /**
+     * Emits the statement(s) that upsert a single embedding into the slot's
+     * storage. Multiple statements are allowed for engines that cannot upsert
+     * a vector in one statement (e.g. a `vec0` virtual table → DELETE+INSERT).
+     */
+    buildUpsert(slot: VectorSlot, params: UpsertEmbeddingParams, timestamp: string): readonly SQL[];
+    /** Emits the statement(s) that delete a single embedding from the slot. */
+    buildDelete(slot: VectorSlot, params: DeleteEmbeddingParams): readonly SQL[];
+    /**
+     * Raw DDL statement(s) that drop the slot's entire physical storage
+     * (table + ANN index, and any engine-managed shadow tables). Used by the
+     * destructive `store.reembedVectorField()` path to recreate a field's
+     * storage at a new dimension. Returned as raw strings (like
+     * `ownedTables(...).createDdl`) for `backend.executeDdl`; must be idempotent
+     * (`IF EXISTS`).
+     */
+    buildDropStorage(slot: VectorSlot): readonly string[];
+    /**
+     * Emits the similarity-search query for the `backend.vectorSearch` path,
+     * returning rows shaped `{ node_id, score }` ordered best-first. The
+     * strategy picks brute-force vs ANN based on whether `slot.indexType`
+     * materialized an index — the caller never branches. `score` follows the
+     * shared convention (cosine → similarity `1 - distance`; l2 /
+     * inner_product → raw distance), so `coerceVectorScore` / fusion stay
+     * dialect-neutral.
+     */
+    buildSearch(slot: VectorSlot, params: VectorSearchParams): SQL;
+    /**
+     * The distance expression over the slot's embedding column, used by the
+     * **query compiler** to splice vector relevance into its CTE. This is the
+     * one genuinely engine-specific fragment (`vec_distance_cosine` vs
+     * `<=>` vs `vector_distance_cos`); the surrounding score / minScore /
+     * ORDER BY math is shared (see {@link vectorScoreExpression} etc.).
+     *
+     * `embeddingColumn` is the already-qualified column SQL; `queryEmbedding`
+     * is formatted by the strategy into its engine's literal form.
+     */
+    distanceExpression(embeddingColumn: SQL, queryEmbedding: readonly number[], metric: VectorMetric): SQL;
+    /**
+     * Emits the ANN index creation statement for a slot, or `undefined` when
+     * indexing is inline (vec0) or unsupported (brute-force-only strategies).
+     * Invoked through `backend.createVectorIndex` during `materializeIndexes`.
+     */
+    buildCreateIndex?(slot: VectorSlot, options?: Readonly<{
+        concurrent?: boolean;
+    }>): SQL | undefined;
+    /** Emits the ANN index drop statement, or `undefined` when not applicable. */
+    buildDropIndex?(slot: VectorSlot): SQL | undefined;
+}
+
+/**
+ * SQL Dialect Abstraction Layer
+ *
+ * Provides a unified interface for dialect-specific SQL generation.
+ * Implementing a new dialect (MySQL, SQL Server, etc.) requires
+ * implementing this interface.
+ */
+
+/**
+ * Supported SQL dialects.
+ */
+type SqlDialect = "sqlite" | "postgres";
+
 /**
  * JSON Schema type (subset used by Zod toJSONSchema).
  *
@@ -541,19 +733,6 @@ type SqliteExecutionProfileHints = Readonly<{
 }>;
 type AnySqliteDatabase = BaseSQLiteDatabase<"sync" | "async", unknown>;
 
-/**
- * SQL Dialect Abstraction Layer
- *
- * Provides a unified interface for dialect-specific SQL generation.
- * Implementing a new dialect (MySQL, SQL Server, etc.) requires
- * implementing this interface.
- */
-
-/**
- * Supported SQL dialects.
- */
-type SqlDialect = "sqlite" | "postgres";
-
 /**
  * Backend interface types for TypeGraph storage.
  *
@@ -618,16 +797,6 @@ type FulltextCapabilities = Readonly<{
  * Backend capabilities that vary by dialect.
  */
 type BackendCapabilities = Readonly<{
-    /** Whether the backend supports JSONB type (vs TEXT for JSON) */
-    jsonb: boolean;
-    /** Whether the backend supports partial indexes */
-    partialIndexes: boolean;
-    /** Whether the backend supports GIN indexes for JSON */
-    ginIndexes: boolean;
-    /** Whether the backend supports CTE (WITH) queries */
-    cte: boolean;
-    /** Whether the backend supports RETURNING clause */
-    returning: boolean;
     /** Whether the backend supports atomic transactions (D1 does not) */
     transactions: boolean;
     /** Vector search capabilities (undefined if not configured) */
@@ -691,19 +860,6 @@ type SchemaVersionRow = Readonly<{
     created_at: string;
     is_active: boolean;
 }>;
-/**
- * A row from the typegraph_node_embeddings table.
- */
-type EmbeddingRow = Readonly<{
-    graph_id: string;
-    node_kind: string;
-    node_id: string;
-    field_path: string;
-    embedding: readonly number[];
-    dimensions: number;
-    created_at: string;
-    updated_at: string;
-}>;
 /**
  * Parameters for inserting a node.
  */
@@ -785,6 +941,14 @@ type HardDeleteEdgeParams = Readonly<{
 }>;
 /**
  * Parameters for inserting or updating an embedding.
+ *
+ * `dimensions`, `metric`, and `indexType` together resolve the slot's
+ * typed per-`(nodeKind, fieldPath)` storage (the strategy needs the fixed
+ * dimension for the column type, and the metric/index type to address the
+ * right ANN structure). The store populates them from the schema's
+ * `embedding()` declaration via `getEmbeddingDimensions()` /
+ * `getEmbeddingIndex()`; the backend constructs a `VectorSlot` from them
+ * and stays graph-agnostic.
  */
 type UpsertEmbeddingParams = Readonly<{
     graphId: string;
@@ -793,15 +957,29 @@ type UpsertEmbeddingParams = Readonly<{
     fieldPath: string;
     embedding: readonly number[];
     dimensions: number;
+    metric: VectorMetric;
+    indexType: VectorIndexType;
 }>;
 /**
  * Parameters for deleting an embedding.
+ *
+ * `dimensions` / `metric` / `indexType` mirror {@link UpsertEmbeddingParams}
+ * so the backend can resolve the slot's typed per-`(nodeKind, fieldPath)`
+ * storage and idempotently ensure it exists before the DELETE. That
+ * matters because a delete can run before any embedding was ever written
+ * (e.g. a node hard-deleted having never carried one), and on Postgres a
+ * DELETE against a missing relation inside a transaction aborts the whole
+ * transaction. The store populates them from the schema's `embedding()`
+ * declaration, exactly as for upserts.
  */
 type DeleteEmbeddingParams = Readonly<{
     graphId: string;
     nodeKind: string;
     nodeId: string;
     fieldPath: string;
+    dimensions: number;
+    metric: VectorMetric;
+    indexType: VectorIndexType;
 }>;
 /**
  * Parameters for vector similarity search.
@@ -812,6 +990,19 @@ type VectorSearchParams = Readonly<{
     fieldPath: string;
     queryEmbedding: readonly number[];
     metric: VectorMetric;
+    /**
+     * Fixed vector dimension `N` for the searched `(nodeKind, fieldPath)`
+     * slot. The store populates it from the schema's `embedding()`
+     * declaration via `getEmbeddingDimensions()`; the backend uses it to
+     * construct the `VectorSlot` whose typed storage the strategy scans.
+     */
+    dimensions: number;
+    /**
+     * Index type materialized for this slot. `"none"` means brute-force
+     * only; otherwise the strategy may route through its ANN structure.
+     * The store populates it from `getEmbeddingIndex()`.
+     */
+    indexType: VectorIndexType;
     limit: number;
     minScore?: number;
     /**
@@ -1170,6 +1361,16 @@ type GraphBackend = Readonly<{
      * When absent, the dialect's default strategy is used.
      */
     fulltextStrategy?: FulltextStrategy | undefined;
+    /**
+     * Optional vector strategy this backend is wired with. The query
+     * compiler reads it (via `compileQuery` options) to emit per-`(kind,
+     * field)` relevance scans for `field.similarTo(...)` predicates, and
+     * the index-materialization / removal paths read its deterministic
+     * `tableName(...)` to address the right physical per-field storage.
+     * `undefined` when the backend has no vector support (e.g. a generic
+     * SQLite backend without sqlite-vec).
+     */
+    vectorStrategy?: VectorStrategy | undefined;
     insertNode: (params: InsertNodeParams) => Promise<NodeRow>;
     insertNodeNoReturn?: (params: InsertNodeParams) => Promise<void>;
     insertNodesBatch?: (params: readonly InsertNodeParams[]) => Promise<void>;
@@ -1234,7 +1435,6 @@ type GraphBackend = Readonly<{
     setActiveVersion: (params: SetActiveVersionParams) => Promise<void>;
     upsertEmbedding?: (params: UpsertEmbeddingParams) => Promise<void>;
     deleteEmbedding?: (params: DeleteEmbeddingParams) => Promise<void>;
-    getEmbedding?: (graphId: string, nodeKind: string, nodeId: string, fieldPath: string) => Promise<EmbeddingRow | undefined>;
     vectorSearch?: (params: VectorSearchParams) => Promise<readonly VectorSearchResult[]>;
     createVectorIndex?: (params: CreateVectorIndexParams) => Promise<void>;
     dropVectorIndex?: (params: DropVectorIndexParams) => Promise<void>;
@@ -1879,8 +2079,12 @@ type VectorSimilarityPredicate = Readonly<{
     field: FieldRef;
     /** The query embedding to compare against */
     queryEmbedding: readonly number[];
-    /** Similarity metric to use */
-    metric: VectorMetricType;
+    /**
+     * Similarity metric. Omitted when the caller didn't pass one — the compiler
+     * then uses the field's DECLARED `embedding()` metric (resolved per kind),
+     * falling back to "cosine" only when no declaration is available.
+     */
+    metric?: VectorMetricType;
     /** Maximum number of results to return */
     limit: number;
     /** Optional minimum similarity score (0-1 for cosine) */
@@ -2398,4 +2602,4 @@ type RelationalIndexDeclaration = NodeIndexDeclaration | EdgeIndexDeclaration;
 type IndexDeclaration = RelationalIndexDeclaration | VectorIndexDeclaration;
 type SystemColumnName = "graph_id" | "kind" | "id" | "from_kind" | "from_id" | "to_kind" | "to_id" | "deleted_at" | "valid_from" | "valid_to" | "created_at" | "updated_at" | "version";
 
-export { type FulltextCapabilities as $, type AnySqliteDatabase as A, type BackendCapabilities as B, type VectorIndexParams as C, type SchemaVersionRow as D, type EdgeIndexConfig as E, type FulltextStrategy as F, type GraphBackend as G, type InferenceType as H, type IndexDeclaration as I, type JsonPointer as J, type AggregateExpr as K, type FieldRef as L, type MetaEdge as M, type NodeIndexConfig as N, type OntologyRelation as O, type ComparisonOp as P, type QueryAst as Q, type RelationalIndexDeclaration as R, type SqliteExecutionProfileHints as S, type AggregateComparisonPredicate as T, type AdoptedTransaction as U, type VectorIndexDeclaration as V, type CommitSchemaVersionExpected as W, type CommitSchemaVersionParams as X, DEFAULT_SQL_SCHEMA as Y, type DeleteFulltextBatchParams as Z, type FulltextBatchRow as _, type SqliteTransactionMode as a, type FulltextQueryMode as a0, type FulltextSearchParams as a1, type FulltextSearchResult as a2, type HybridFusionOptions as a3, type JsonPointerFor as a4, type JsonPointerInput as a5, type JsonPointerSegment as a6, type JsonPointerSegments as a7, type JsonPointerSegmentsFor as a8, MAX_JSON_POINTER_DEPTH as a9, type Traversal as aA, type NodePredicate as aB, type ProjectedField as aC, type GroupBySpec as aD, type RecursiveCyclePolicy as aE, type TraversalDirection as aF, type EdgeRow as aG, type NodeRow as aH, type SelectiveField as aI, type ComposableQuery as aJ, type SetOperationType as aK, type SetOperation as aL, type VectorMetric as aM, type MetaEdgeProperties as aa, type OrderSpec as ab, type ParameterRef as ac, type ResolveJsonPointer as ad, type ResolveJsonPointerSegments as ae, type SetActiveVersionParams as af, type SortDirection as ag, type SqlSchema as ah, type SqlTableNames as ai, type StrategyTableContribution as aj, type TableContribution as ak, type TransactionBackend as al, type TraversalExpansion as am, type UpsertFulltextBatchParams as an, type VectorCapabilities as ao, createSqlSchema as ap, fts5Strategy as aq, isMetaEdge as ar, joinJsonPointers as as, jsonPointer as at, normalizeJsonPointer as au, parseJsonPointer as av, tsvectorStrategy as aw, type ValueType as ax, type PredicateExpression as ay, type VectorMetricType as az, type AnyPgDatabase as b, type EdgeIndexDeclaration as c, type NodeIndexDeclaration as d, type IndexWhereExpression as e, type SerializedNodeDef as f, type SerializedEdgeDef as g, type SerializedMetaEdge as h, type SerializedOntologyRelation as i, type SerializedClosures as j, type SerializedSchema as k, type SchemaHash as l, type JsonSchema as m, type SerializedOntology as n, type SerializedUniqueConstraint as o, type SqlDialect as p, type EdgeIndexDirection as q, type EdgeIndexWhereBuilder as r, type IndexOrigin as s, type IndexScope as t, type IndexWhereFieldBuilder as u, type IndexWhereInput as v, type NodeIndexWhereBuilder as w, type SystemColumnName as x, type VectorIndexImplementation as y, type VectorIndexMetric as z };
+export { type FulltextBatchRow as $, type AnySqliteDatabase as A, type BackendCapabilities as B, type VectorIndexMetric as C, type VectorIndexParams as D, type EdgeIndexConfig as E, type FulltextStrategy as F, type GraphBackend as G, type SchemaVersionRow as H, type IndexDeclaration as I, type JsonPointer as J, type InferenceType as K, type AggregateExpr as L, type MetaEdge as M, type NodeIndexConfig as N, type OntologyRelation as O, type FieldRef as P, type QueryAst as Q, type RelationalIndexDeclaration as R, type SqliteExecutionProfileHints as S, type ComparisonOp as T, type AggregateComparisonPredicate as U, type VectorStrategy as V, type AdoptedTransaction as W, type CommitSchemaVersionExpected as X, type CommitSchemaVersionParams as Y, DEFAULT_SQL_SCHEMA as Z, type DeleteFulltextBatchParams as _, type SqliteTransactionMode as a, type FulltextCapabilities as a0, type FulltextQueryMode as a1, type FulltextSearchParams as a2, type FulltextSearchResult as a3, type HybridFusionOptions as a4, type JsonPointerFor as a5, type JsonPointerInput as a6, type JsonPointerSegment as a7, type JsonPointerSegments as a8, type JsonPointerSegmentsFor as a9, type VectorSlotMap as aA, type ValueType as aB, type PredicateExpression as aC, type VectorMetricType as aD, type Traversal as aE, type NodePredicate as aF, type ProjectedField as aG, type GroupBySpec as aH, type RecursiveCyclePolicy as aI, type TraversalDirection as aJ, type EdgeRow as aK, type NodeRow as aL, type SelectiveField as aM, type ComposableQuery as aN, type SetOperationType as aO, type SetOperation as aP, type VectorMetric as aQ, MAX_JSON_POINTER_DEPTH as aa, type MetaEdgeProperties as ab, type OrderSpec as ac, type ParameterRef as ad, type ResolveJsonPointer as ae, type ResolveJsonPointerSegments as af, type SetActiveVersionParams as ag, type SortDirection as ah, type SqlSchema as ai, type SqlTableNames as aj, type StrategyTableContribution as ak, type TableContribution as al, type TransactionBackend as am, type TraversalExpansion as an, type UpsertFulltextBatchParams as ao, type VectorCapabilities as ap, type VectorSlot as aq, buildVectorCapabilities as ar, createSqlSchema as as, fts5Strategy as at, isMetaEdge as au, joinJsonPointers as av, jsonPointer as aw, normalizeJsonPointer as ax, parseJsonPointer as ay, tsvectorStrategy as az, type AnyPgDatabase as b, type EdgeIndexDeclaration as c, type NodeIndexDeclaration as d, type IndexWhereExpression as e, type SerializedNodeDef as f, type SerializedEdgeDef as g, type SerializedMetaEdge as h, type SerializedOntologyRelation as i, type SerializedClosures as j, type SerializedSchema as k, type SchemaHash as l, type JsonSchema as m, type SerializedOntology as n, type SerializedUniqueConstraint as o, type SqlDialect as p, type EdgeIndexDirection as q, type EdgeIndexWhereBuilder as r, type IndexOrigin as s, type IndexScope as t, type IndexWhereFieldBuilder as u, type IndexWhereInput as v, type NodeIndexWhereBuilder as w, type SystemColumnName as x, type VectorIndexDeclaration as y, type VectorIndexImplementation as z };