@nicia-ai/typegraph 0.24.1 → 0.25.0

package/dist/types--0EslBx5.d.cts

@@ -0,0 +1,2123 @@
+import { z } from 'zod';
+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-D07e_NTw.cjs';
+import { SQL } from 'drizzle-orm';
+
+/** Brand key for MetaEdge */
+declare const META_EDGE_BRAND: "__metaEdge";
+/**
+ * How a meta-edge affects queries and validation.
+ */
+type InferenceType = "subsumption" | "hierarchy" | "substitution" | "constraint" | "composition" | "association" | "none";
+/**
+ * Properties of a meta-edge.
+ */
+type MetaEdgeProperties = Readonly<{
+    transitive: boolean;
+    symmetric: boolean;
+    reflexive: boolean;
+    inverse: string | undefined;
+    inference: InferenceType;
+    description: string | undefined;
+}>;
+/**
+ * A meta-edge definition.
+ *
+ * Meta-edges represent type-level relationships (between kinds),
+ * not instance-level relationships (between nodes).
+ */
+type MetaEdge<K extends string = string> = Readonly<{
+    [META_EDGE_BRAND]: true;
+    name: K;
+    properties: MetaEdgeProperties;
+}>;
+/**
+ * A relation in the ontology (instance of meta-edge between types).
+ *
+ * @example
+ * ```typescript
+ * // Podcast subClassOf Media
+ * subClassOf(Podcast, Media)
+ *
+ * // Person equivalentTo schema:Person
+ * equivalentTo(Person, "https://schema.org/Person")
+ * ```
+ */
+type OntologyRelation = Readonly<{
+    metaEdge: MetaEdge;
+    from: NodeType | EdgeType | string;
+    to: NodeType | EdgeType | string;
+}>;
+/**
+ * Checks if a value is a MetaEdge.
+ */
+declare function isMetaEdge(value: unknown): value is MetaEdge;
+
+declare const MAX_JSON_POINTER_DEPTH: 5;
+type JsonPointer = string & {
+    readonly __jsonPointer: unique symbol;
+};
+type JsonPointerSegment = string | number;
+type JsonPointerSegments = readonly JsonPointerSegment[];
+type Depth = 0 | 1 | 2 | 3 | 4 | 5;
+interface DepthDecrementMap {
+    0: 0;
+    1: 0;
+    2: 1;
+    3: 2;
+    4: 3;
+    5: 4;
+}
+type Decrement<Current extends Depth> = DepthDecrementMap[Current];
+type NonNegativeIntegerString = Exclude<`${bigint}`, `-${string}`>;
+type ObjectPointerKey<T> = Exclude<Extract<keyof T, string>, NonNegativeIntegerString>;
+type EncodeTilde<S extends string> = S extends `${infer Head}~${infer Tail}` ? `${EncodeTilde<Head>}~0${EncodeTilde<Tail>}` : S;
+type EncodeSlash<S extends string> = S extends `${infer Head}/${infer Tail}` ? `${EncodeSlash<Head>}~1${EncodeSlash<Tail>}` : S;
+type EncodePointerSegment<S extends string> = EncodeSlash<EncodeTilde<S>>;
+type DecodePointerSegment<S extends string> = S extends `${infer Head}~1${infer Tail}` ? `${DecodePointerSegment<Head>}/${DecodePointerSegment<Tail>}` : S extends `${infer Head}~0${infer Tail}` ? `${DecodePointerSegment<Head>}~${DecodePointerSegment<Tail>}` : S;
+type PointerForArray<T, Current extends Depth> = `/${NonNegativeIntegerString}` | (Current extends 1 ? never : `/${NonNegativeIntegerString}${JsonPointerFor<T, Decrement<Current>>}`);
+type PointerForObject<T, Current extends Depth> = {
+    [K in ObjectPointerKey<T>]: `/${EncodePointerSegment<K>}` | (Current extends 1 ? never : `/${EncodePointerSegment<K>}${JsonPointerFor<T[K], Decrement<Current>>}`);
+}[ObjectPointerKey<T>];
+type JsonPointerFor<T, Current extends Depth = 5> = "" | (Current extends 0 ? "" : T extends readonly (infer U)[] ? PointerForArray<U, Current> : never) | (Current extends 0 ? "" : T extends Record<string, unknown> ? PointerForObject<T, Current> : never);
+type PointerSegmentsForArray<T, Current extends Depth> = readonly [number] | (Current extends 1 ? readonly [number] : readonly [number, ...JsonPointerSegmentsFor<T, Decrement<Current>>]);
+type PointerSegmentsForObject<T, Current extends Depth> = {
+    [K in ObjectPointerKey<T>]: readonly [K] | (Current extends 1 ? readonly [K] : readonly [K, ...JsonPointerSegmentsFor<T[K], Decrement<Current>>]);
+}[ObjectPointerKey<T>];
+type JsonPointerSegmentsFor<T, Current extends Depth = 5> = readonly [] | (Current extends 0 ? readonly [] : T extends readonly (infer U)[] ? PointerSegmentsForArray<U, Current> : never) | (Current extends 0 ? readonly [] : T extends Record<string, unknown> ? PointerSegmentsForObject<T, Current> : never);
+type JsonPointerInput<T> = JsonPointerFor<T> | JsonPointerSegmentsFor<T> | JsonPointer;
+type ResolveJsonPointer<T, Pointer extends string> = Pointer extends "" ? T : Pointer extends `/${infer Head}/${infer Tail}` ? ResolveJsonPointer<ResolvePointerSegment<T, DecodePointerSegment<Head>>, `/${Tail}`> : Pointer extends `/${infer Head}` ? ResolvePointerSegment<T, DecodePointerSegment<Head>> : unknown;
+type ResolvePointerSegment<T, Segment extends string> = T extends readonly (infer U)[] ? Segment extends NonNegativeIntegerString ? U : unknown : T extends Record<string, unknown> ? Segment extends keyof T ? Segment extends NonNegativeIntegerString ? unknown : T[Segment] : unknown : unknown;
+type ResolveJsonPointerSegments<T, Segments extends readonly JsonPointerSegment[]> = Segments extends readonly [] ? T : Segments extends readonly [infer Head, ...infer Tail] ? ResolveJsonPointerSegments<ResolvePointerSegment<T, SegmentToString<Head>>, Extract<Tail, readonly JsonPointerSegment[]>> : unknown;
+type SegmentToString<Segment> = Segment extends number ? `${Segment}` : Segment extends string ? Segment : string;
+declare function jsonPointer(segments: JsonPointerSegments): JsonPointer;
+declare function normalizeJsonPointer<T>(input: JsonPointerInput<T>): JsonPointer;
+declare function parseJsonPointer(pointer: JsonPointer): readonly string[];
+declare function joinJsonPointers(base: JsonPointer | undefined, relative: JsonPointer): JsonPointer;
+
+/**
+ * SQL Schema Configuration for Query Compilation
+ *
+ * Provides table and column identifiers that the query compiler uses.
+ * This allows the compiler to work with custom table names instead of
+ * hard-coded defaults.
+ */
+
+/**
+ * Table names for TypeGraph SQL schema.
+ *
+ * Carries every customizable physical-table name the backend exposes,
+ * including the secondary tables (`uniques`) that the query compiler
+ * itself doesn't reference but `materializeRemovals` and other
+ * cleanup paths need to address by name. Backends without a
+ * `uniques` table (custom embeddings-only stores) leave it as the
+ * default — the cleanup path is a no-op for kinds with no unique
+ * rows.
+ */
+type SqlTableNames = Readonly<{
+    /** Nodes table name (default: "typegraph_nodes") */
+    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") */
+    uniques: string;
+}>;
+/**
+ * SQL schema configuration for query compilation.
+ * Contains table identifiers and utility methods for generating SQL references.
+ */
+type SqlSchema = Readonly<{
+    /** Table names */
+    tables: SqlTableNames;
+    /** Get a SQL reference to the nodes table */
+    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;
+}>;
+/**
+ * Creates a SqlSchema configuration from table names.
+ *
+ * Table names are validated to ensure they are valid SQL identifiers.
+ * This prevents SQL injection and ensures compatibility across databases.
+ *
+ * @param names - Optional custom table names (defaults to standard names)
+ * @returns SqlSchema configuration for query compilation
+ * @throws Error if any table name is invalid
+ *
+ * @example
+ * ```typescript
+ * // Use default table names
+ * const schema = createSqlSchema();
+ *
+ * // Use custom table names
+ * const schema = createSqlSchema({
+ *   nodes: "myapp_nodes",
+ *   edges: "myapp_edges",
+ *   embeddings: "myapp_embeddings",
+ * });
+ * ```
+ */
+declare function createSqlSchema(names?: Partial<SqlTableNames>): SqlSchema;
+/**
+ * Default SqlSchema using standard TypeGraph table names.
+ */
+declare const DEFAULT_SQL_SCHEMA: SqlSchema;
+
+/**
+ * Fulltext Strategy — pluggable DDL + SQL generation for a dialect's
+ * fulltext stack. A strategy owns every SQL statement that touches its
+ * backing table: DDL, upsert (single + batch), delete (single + batch),
+ * MATCH condition, rank expression, and snippet expression.
+ *
+ * A dialect picks one as its default; `createPostgresBackend` /
+ * `createSqliteBackend` accept an override for alternate Postgres stacks
+ * (pg_trgm, ParadeDB/pg_search, pgroonga) to swap the entire fulltext
+ * pipeline without forking TypeGraph.
+ */
+
+/**
+ * A pluggable fulltext implementation. Each strategy is expected to be
+ * self-contained: given a table name, a query string, and a parse mode,
+ * it emits every SQL statement the compiler and backend need — DDL,
+ * reads, and writes. No out-of-band conventions across layers.
+ */
+interface FulltextStrategy {
+    /** Human-readable identifier used in error messages and telemetry. */
+    readonly name: string;
+    /**
+     * Parse modes this strategy can translate. Callers validate against
+     * this list before emitting SQL; a mode outside the set means the
+     * strategy rejects the query at compile time.
+     */
+    readonly supportedModes: readonly FulltextQueryMode[];
+    /**
+     * Whether the strategy can emit a per-row highlighted snippet. When
+     * false, `snippetExpression` returns a literal `NULL` so callers can
+     * leave the `snippet` column in place without a branch.
+     */
+    readonly supportsSnippets: boolean;
+    /**
+     * Whether the strategy supports prefix queries (`foo*`). Used to
+     * populate `BackendCapabilities.fulltext.prefixQueries`. A strategy
+     * may support prefix queries via dedicated syntax without advertising
+     * "raw" mode (and vice-versa).
+     */
+    readonly supportsPrefix: boolean;
+    /**
+     * Whether a per-query `language` override is honored. Postgres' tsvector
+     * accepts any installed regconfig at query time; SQLite FTS5's tokenizer
+     * is fixed at table-create time, so the override is silently ignored.
+     * Callers may surface a warning when the user passes `language` to a
+     * strategy that doesn't honor it.
+     */
+    readonly supportsLanguageOverride: boolean;
+    /**
+     * Languages / tokenizer names understood by the strategy. Advisory — a
+     * runtime backend like Postgres may accept other installed regconfigs.
+     * Used to populate `BackendCapabilities.fulltext.languages`.
+     */
+    readonly languages: readonly string[];
+    /**
+     * Emits the WHERE-side MATCH expression.
+     *
+     * @example
+     * tsvector: `"typegraph_node_fulltext"."tsv" @@ websearch_to_tsquery('english', 'cats')`
+     * fts5:     `"typegraph_node_fulltext" MATCH '"cats"'`
+     */
+    matchCondition(tableName: string, query: string, mode: FulltextQueryMode, language?: string): SQL;
+    /**
+     * Emits the relevance expression. Higher values = more relevant. The
+     * compiler orders by this expression DESC, and both builder and
+     * backend-direct paths use the same form so their top-k results agree.
+     */
+    rankExpression(tableName: string, query: string, mode: FulltextQueryMode, language?: string): SQL;
+    /**
+     * Emits a per-row highlighted snippet expression, or `NULL` when
+     * `supportsSnippets` is false. Snippet markup is `<mark>…</mark>` in
+     * both shipped strategies so consumers can apply one stylesheet.
+     */
+    snippetExpression(tableName: string, query: string, mode: FulltextQueryMode, language?: string): SQL;
+    /**
+     * DDL statements to create the backing table and any supporting
+     * indexes. Idempotent (`CREATE ... IF NOT EXISTS`). Called once from
+     * `bootstrapTables()` on a fresh database.
+     */
+    generateDdl(tableName: string): readonly string[];
+    /**
+     * Emits the statements that upsert a single fulltext row. Returns one
+     * or more statements — some backends (SQLite FTS5) cannot emulate
+     * upsert in a single statement and need DELETE + INSERT.
+     */
+    buildUpsert(tableName: string, params: UpsertFulltextParams, timestamp: string): readonly SQL[];
+    /**
+     * Emits the statements that upsert many fulltext rows at once. Input
+     * rows are expected to be de-duplicated last-write-wins by the
+     * strategy if the underlying SQL statement cannot tolerate duplicate
+     * conflict keys. Returns `[]` when `params.rows` is empty.
+     */
+    buildBatchUpsert(tableName: string, params: UpsertFulltextBatchParams, timestamp: string): readonly SQL[];
+    /**
+     * Emits the statements that delete a single fulltext row. Normally a
+     * single PK-scoped DELETE, but strategies that maintain auxiliary
+     * indexes (delete-triggered external stores, ParadeDB-style secondary
+     * structures) may need more.
+     */
+    buildDelete(tableName: string, params: DeleteFulltextParams): readonly SQL[];
+    /**
+     * Emits the statements that delete many fulltext rows at once. Returns
+     * `[]` when `params.nodeIds` is empty.
+     */
+    buildBatchDelete(tableName: string, params: DeleteFulltextBatchParams): readonly SQL[];
+}
+declare const tsvectorStrategy: FulltextStrategy;
+declare const fts5Strategy: FulltextStrategy;
+
+/**
+ * JSON Schema type (subset used by Zod toJSONSchema).
+ *
+ * This is a simplified version - the actual JSON Schema has many more properties.
+ */
+type JsonSchema = Readonly<{
+    $schema?: string;
+    type?: string | readonly string[];
+    properties?: Record<string, JsonSchema>;
+    required?: readonly string[];
+    items?: JsonSchema;
+    additionalProperties?: boolean | JsonSchema;
+    enum?: readonly unknown[];
+    const?: unknown;
+    anyOf?: readonly JsonSchema[];
+    oneOf?: readonly JsonSchema[];
+    allOf?: readonly JsonSchema[];
+    not?: JsonSchema;
+    description?: string;
+    default?: unknown;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: string;
+    [key: string]: unknown;
+}>;
+/**
+ * Serialized representation of a meta-edge.
+ */
+type SerializedMetaEdge = Readonly<{
+    name: string;
+    transitive: boolean;
+    symmetric: boolean;
+    reflexive: boolean;
+    inverse: string | undefined;
+    inference: InferenceType;
+    description: string | undefined;
+}>;
+/**
+ * Serialized representation of an ontology relation.
+ */
+type SerializedOntologyRelation = Readonly<{
+    metaEdge: string;
+    from: string;
+    to: string;
+}>;
+/**
+ * Precomputed closures stored in the schema for fast runtime lookup.
+ */
+type SerializedClosures = Readonly<{
+    subClassAncestors: Record<string, readonly string[]>;
+    subClassDescendants: Record<string, readonly string[]>;
+    broaderClosure: Record<string, readonly string[]>;
+    narrowerClosure: Record<string, readonly string[]>;
+    equivalenceSets: Record<string, readonly string[]>;
+    disjointPairs: readonly string[];
+    partOfClosure: Record<string, readonly string[]>;
+    hasPartClosure: Record<string, readonly string[]>;
+    iriToKind: Record<string, string>;
+    edgeInverses: Record<string, string>;
+    edgeImplicationsClosure: Record<string, readonly string[]>;
+    edgeImplyingClosure: Record<string, readonly string[]>;
+}>;
+/**
+ * Complete serialized ontology section.
+ */
+type SerializedOntology = Readonly<{
+    metaEdges: Record<string, SerializedMetaEdge>;
+    relations: readonly SerializedOntologyRelation[];
+    closures: SerializedClosures;
+}>;
+/**
+ * Serialized representation of a uniqueness constraint.
+ */
+type SerializedUniqueConstraint = Readonly<{
+    name: string;
+    fields: readonly string[];
+    where: string | undefined;
+    scope: UniquenessScope;
+    collation: Collation;
+}>;
+/**
+ * Serialized representation of a node kind.
+ */
+type SerializedNodeDef = Readonly<{
+    kind: string;
+    properties: JsonSchema;
+    uniqueConstraints: readonly SerializedUniqueConstraint[];
+    onDelete: DeleteBehavior;
+    description: string | undefined;
+    annotations?: KindAnnotations;
+}>;
+/**
+ * Serialized representation of an edge kind.
+ */
+type SerializedEdgeDef = Readonly<{
+    kind: string;
+    fromKinds: readonly string[];
+    toKinds: readonly string[];
+    properties: JsonSchema;
+    cardinality: Cardinality;
+    endpointExistence: EndpointExistence;
+    description: string | undefined;
+    annotations?: KindAnnotations;
+}>;
+/**
+ * Complete serialized schema document.
+ *
+ * This is the format stored in the schema_doc column of
+ * typegraph_schema_versions. The type is kept explicit rather than
+ * inferred from the Zod schema so that downstream code sees the
+ * precise literal union types (DeleteBehavior, TemporalMode, etc.)
+ * instead of the broader `string` type that Zod's passthrough schema uses.
+ */
+type SerializedSchema = Readonly<{
+    graphId: string;
+    version: number;
+    generatedAt: string;
+    nodes: Record<string, SerializedNodeDef>;
+    edges: Record<string, SerializedEdgeDef>;
+    ontology: SerializedOntology;
+    defaults: Readonly<{
+        onNodeDelete: DeleteBehavior;
+        temporalMode: TemporalMode;
+    }>;
+    /**
+     * Index declarations attached to the graph.
+     *
+     * Omitted entirely when the graph never declared the slice — legacy
+     * schemas hash byte-identically to before `indexes` existed. Each
+     * entry carries an `origin` discriminator: `"compile-time"` is the
+     * default and is omitted from the canonical form (see `serializer.ts`);
+     * only `"runtime"` is emitted explicitly.
+     */
+    indexes?: readonly IndexDeclaration[];
+    /**
+     * Graph extension, when this schema was produced from a graph that
+     * had been merged with one. The loader uses this value (and only
+     * this value) to rebuild extension-kind Zod validators on restart —
+     * the merged `nodes` / `edges` / `ontology` maps above carry the
+     * JSON-Schema-shaped views for diff machinery and human-readable
+     * reporting, but they cannot reconstruct Zod alone.
+     *
+     * Omitted entirely on graphs that have never been extended — legacy
+     * schemas hash byte-identically.
+     */
+    extension?: GraphExtension;
+    /**
+     * Soft-deprecated node and edge kind names. Set by
+     * `store.deprecateKinds(...)`; cleared by `store.undeprecateKinds(...)`.
+     * Surfaces in introspection but does not affect reads, writes, or
+     * queries. Omitted entirely when empty so legacy schemas hash
+     * byte-identically.
+     */
+    deprecatedKinds?: readonly string[];
+}>;
+/**
+ * A schema hash for detecting changes.
+ *
+ * We hash the schema content (excluding version and generatedAt)
+ * to detect if the schema has actually changed.
+ */
+type SchemaHash = string;
+
+/**
+ * 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.
+ *
+ * The backend abstracts database operations, allowing different
+ * SQL implementations (SQLite, PostgreSQL) behind a common interface.
+ */
+
+/**
+ * Supported vector similarity metrics.
+ */
+type VectorMetric = "cosine" | "l2" | "inner_product";
+/**
+ * Supported vector index types.
+ */
+type VectorIndexType = "hnsw" | "ivfflat" | "none";
+/**
+ * Vector search capabilities.
+ */
+type VectorCapabilities = Readonly<{
+    /** Whether the backend supports vector operations */
+    supported: boolean;
+    /** Supported similarity metrics */
+    metrics: readonly VectorMetric[];
+    /** Supported index types */
+    indexTypes: readonly VectorIndexType[];
+    /** Maximum dimensions supported */
+    maxDimensions: number;
+}>;
+/**
+ * Query modes for fulltext search.
+ *
+ * - "websearch": Google-style syntax (quoted phrases, +required, -excluded).
+ *    Postgres: `websearch_to_tsquery`. SQLite: translated to FTS5 MATCH.
+ * - "phrase": treats the whole query as a phrase.
+ *    Postgres: `phraseto_tsquery`. SQLite: FTS5 `"..."` phrase.
+ * - "plain": splits on whitespace and ANDs terms.
+ *    Postgres: `plainto_tsquery`. SQLite: default FTS5 AND.
+ * - "raw": dialect-native syntax passed through unchanged.
+ */
+type FulltextQueryMode = "websearch" | "phrase" | "plain" | "raw";
+/**
+ * Fulltext search capabilities declared by a backend.
+ */
+type FulltextCapabilities = Readonly<{
+    /** Whether the backend supports fulltext operations */
+    supported: boolean;
+    /**
+     * Language / tokenizer names understood by this backend.
+     * Postgres: installed regconfigs (english, simple, ...).
+     * SQLite FTS5: tokenizer names (unicode61, porter, trigram).
+     */
+    languages: readonly string[];
+    /** Whether phrase queries are supported. */
+    phraseQueries: boolean;
+    /** Whether prefix (`foo*`) queries are supported. */
+    prefixQueries: boolean;
+    /** Whether highlighting / snippets are supported. */
+    highlighting: boolean;
+}>;
+
+/**
+ * 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) */
+    vector?: VectorCapabilities | undefined;
+    /** Fulltext search capabilities (undefined if not configured) */
+    fulltext?: FulltextCapabilities | undefined;
+}>;
+/**
+ * A row from the typegraph_nodes table.
+ */
+type NodeRow = Readonly<{
+    graph_id: string;
+    kind: string;
+    id: string;
+    props: string;
+    version: number;
+    valid_from: string | undefined;
+    valid_to: string | undefined;
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | undefined;
+}>;
+/**
+ * A row from the typegraph_edges table.
+ */
+type EdgeRow = Readonly<{
+    graph_id: string;
+    id: string;
+    kind: string;
+    from_kind: string;
+    from_id: string;
+    to_kind: string;
+    to_id: string;
+    props: string;
+    valid_from: string | undefined;
+    valid_to: string | undefined;
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | undefined;
+}>;
+/**
+ * A row from the typegraph_node_uniques table.
+ */
+type UniqueRow = Readonly<{
+    graph_id: string;
+    node_kind: string;
+    constraint_name: string;
+    key: string;
+    node_id: string;
+    concrete_kind: string;
+    deleted_at: string | undefined;
+}>;
+/**
+ * A row from the typegraph_schema_versions table.
+ */
+type SchemaVersionRow = Readonly<{
+    graph_id: string;
+    version: number;
+    schema_hash: string;
+    schema_doc: string;
+    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.
+ */
+type InsertNodeParams = Readonly<{
+    graphId: string;
+    kind: string;
+    id: string;
+    props: Readonly<Record<string, unknown>>;
+    validFrom?: string;
+    validTo?: string;
+}>;
+/**
+ * Parameters for updating a node.
+ */
+type UpdateNodeParams = Readonly<{
+    graphId: string;
+    kind: string;
+    id: string;
+    props: Readonly<Record<string, unknown>>;
+    validTo?: string;
+    incrementVersion?: boolean;
+    /** If true, clears deleted_at (un-deletes the node). Used by upsert. */
+    clearDeleted?: boolean;
+}>;
+/**
+ * Parameters for deleting a node (soft delete).
+ */
+type DeleteNodeParams = Readonly<{
+    graphId: string;
+    kind: string;
+    id: string;
+}>;
+/**
+ * Parameters for inserting an edge.
+ */
+type InsertEdgeParams = Readonly<{
+    graphId: string;
+    id: string;
+    kind: string;
+    fromKind: string;
+    fromId: string;
+    toKind: string;
+    toId: string;
+    props: Readonly<Record<string, unknown>>;
+    validFrom?: string;
+    validTo?: string;
+}>;
+/**
+ * Parameters for updating an edge.
+ */
+type UpdateEdgeParams = Readonly<{
+    graphId: string;
+    id: string;
+    props: Readonly<Record<string, unknown>>;
+    validTo?: string;
+    clearDeleted?: boolean;
+}>;
+/**
+ * Parameters for deleting an edge (soft delete).
+ */
+type DeleteEdgeParams = Readonly<{
+    graphId: string;
+    id: string;
+}>;
+/**
+ * Parameters for hard deleting a node (permanent removal).
+ */
+type HardDeleteNodeParams = Readonly<{
+    graphId: string;
+    kind: string;
+    id: string;
+}>;
+/**
+ * Parameters for hard deleting an edge (permanent removal).
+ */
+type HardDeleteEdgeParams = Readonly<{
+    graphId: string;
+    id: string;
+}>;
+/**
+ * Parameters for inserting or updating an embedding.
+ */
+type UpsertEmbeddingParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    nodeId: string;
+    fieldPath: string;
+    embedding: readonly number[];
+    dimensions: number;
+}>;
+/**
+ * Parameters for deleting an embedding.
+ */
+type DeleteEmbeddingParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    nodeId: string;
+    fieldPath: string;
+}>;
+/**
+ * Parameters for vector similarity search.
+ */
+type VectorSearchParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    fieldPath: string;
+    queryEmbedding: readonly number[];
+    metric: VectorMetric;
+    limit: number;
+    minScore?: number;
+}>;
+/**
+ * Result from a vector similarity search.
+ */
+type VectorSearchResult = Readonly<{
+    nodeId: string;
+    /**
+     * Cosine metric returns similarity score (higher is better).
+     * L2 and inner_product return raw distance (lower is better).
+     */
+    score: number;
+}>;
+/**
+ * Parameters for creating a vector index.
+ */
+type CreateVectorIndexParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    fieldPath: string;
+    dimensions: number;
+    metric: VectorMetric;
+    indexType: VectorIndexType;
+    /** Index-specific parameters */
+    indexParams?: Readonly<{
+        /** HNSW: max connections per layer */
+        m?: number;
+        /** HNSW: construction search depth */
+        efConstruction?: number;
+        /** IVFFlat: number of lists */
+        lists?: number;
+    }>;
+    /**
+     * Build the index without taking an `AccessExclusiveLock` on live
+     * tables (Postgres `CREATE INDEX CONCURRENTLY`). Mirrors the
+     * `concurrent` flag the relational DDL path uses inside
+     * `materializeIndexes()`. Cannot be set inside a transaction —
+     * callers (`materializeIndexes()`) run at top level. Backends that
+     * don't have a CONCURRENTLY equivalent (SQLite) ignore this flag.
+     */
+    concurrent?: boolean;
+}>;
+/**
+ * Parameters for dropping a vector index.
+ */
+type DropVectorIndexParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    fieldPath: string;
+}>;
+/**
+ * Parameters for inserting or updating a fulltext entry.
+ *
+ * One row per node. Callers concatenate the searchable fields into
+ * `content` so a single MATCH query can find terms spread across fields.
+ *
+ * Note: `createFulltextIndex` / `dropFulltextIndex` were removed as
+ * dead code in #PR_E. The fulltext table's canonical index (Postgres
+ * GIN on `tsv`, SQLite FTS5 virtual table) is created with the table
+ * itself by `bootstrapTables` per the active `FulltextStrategy`;
+ * per-kind fulltext indexes are an "advanced strategy" surface that
+ * doesn't fit the relational-style declaration model and is reserved
+ * for future work.
+ */
+type UpsertFulltextParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    nodeId: string;
+    content: string;
+    language: string;
+}>;
+/**
+ * Parameters for deleting a single fulltext entry.
+ */
+type DeleteFulltextParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    nodeId: string;
+}>;
+/**
+ * A single row in a fulltext batch upsert.
+ */
+type FulltextBatchRow = Readonly<{
+    nodeId: string;
+    content: string;
+    language: string;
+}>;
+/**
+ * Parameters for a batched fulltext upsert.
+ *
+ * Homogeneous: one graph, one node kind, many nodes. Duplicate `nodeId`
+ * values within a single batch are deduplicated last-write-wins by the
+ * builders before SQL generation — Postgres `ON CONFLICT` errors on
+ * repeated conflict keys in one statement, and SQLite `DELETE + INSERT`
+ * would create duplicate virtual-table rows otherwise.
+ */
+type UpsertFulltextBatchParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    rows: readonly FulltextBatchRow[];
+}>;
+/**
+ * Parameters for a batched fulltext delete.
+ */
+type DeleteFulltextBatchParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    nodeIds: readonly string[];
+}>;
+/**
+ * Parameters for fulltext search.
+ */
+type FulltextSearchParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    /** The user-supplied query string. */
+    query: string;
+    /** How to parse `query`. Default: "websearch". */
+    mode?: FulltextQueryMode;
+    /**
+     * Language override. Default: per-row language (as stored at insert time).
+     * Postgres: passed as the regconfig to `to_tsquery` / `websearch_to_tsquery`.
+     * SQLite: informational only (FTS5 tokenizer is fixed at table-create time).
+     */
+    language?: string;
+    /** Max rows to return. */
+    limit: number;
+    /** Minimum rank to include (backend-dependent units). */
+    minScore?: number;
+    /** Whether to return a highlighted snippet per match. */
+    includeSnippets?: boolean;
+}>;
+/**
+ * Result from a fulltext search.
+ *
+ * Score semantics differ by backend; prefer `rank` (1-based) when fusing
+ * with another source via RRF.
+ */
+type FulltextSearchResult = Readonly<{
+    nodeId: string;
+    /**
+     * Backend-native relevance score.
+     * Postgres: `ts_rank_cd` (higher is better).
+     * SQLite FTS5: negated `bm25()` (higher is better; FTS5 returns lower-is-better).
+     */
+    score: number;
+    /** 1-based rank within the result set, suitable for RRF. */
+    rank: number;
+    /** Highlighted snippet of the content (if `includeSnippets` was set). */
+    snippet?: string;
+}>;
+/**
+ * Parameters for creating a fulltext index.
+ *
+ * The canonical index (Postgres GIN on `tsv`, SQLite FTS5 virtual table)
+ * is created when the fulltext table itself is created. This is reserved
+ * for advanced per-kind specializations.
+ */
+/**
+ * Per-deployment record for a single declared index.
+ *
+ * Identified by `indexName` because SQL index names are physical,
+ * database-global identifiers — `graphId` is provenance, not identity.
+ * `materializedAt` is null until the first successful CREATE INDEX
+ * completes; `lastAttemptedAt` is always set, even on failure.
+ */
+type IndexMaterializationRow = Readonly<{
+    indexName: string;
+    graphId: string;
+    entity: IndexEntity;
+    kind: string;
+    signature: string;
+    schemaVersion: number;
+    materializedAt: string | undefined;
+    lastAttemptedAt: string;
+    lastError: string | undefined;
+}>;
+/**
+ * Parameters for upserting a materialization attempt.
+ *
+ * On success: pass `materializedAt` (ISO timestamp) and undefined `error`.
+ * On failure: pass undefined `materializedAt` (preserve any existing
+ * timestamp from a prior success) and the error message.
+ */
+type RecordIndexMaterializationParams = Readonly<{
+    indexName: string;
+    graphId: string;
+    entity: IndexEntity;
+    kind: string;
+    signature: string;
+    schemaVersion: number;
+    attemptedAt: string;
+    /** ISO timestamp on success; undefined on failure (preserves existing). */
+    materializedAt: string | undefined;
+    /** Error message on failure; undefined on success (clears existing). */
+    error: string | undefined;
+}>;
+/**
+ * One row of the per-deployment `typegraph_kind_removals` table:
+ * a graph-extension kind that has been removed from the schema and whose
+ * data may or may not have been cleaned up yet.
+ */
+type KindRemovalRow = Readonly<{
+    graphId: string;
+    kindName: string;
+    entity: KindEntity;
+    schemaVersion: number;
+    /** ISO timestamp when the data-cleanup pass succeeded; undefined while pending. */
+    removedAt: string | undefined;
+    lastAttemptedAt: string;
+    lastError: string | undefined;
+}>;
+/**
+ * Upsert payload for a kind-removal status row. On removal-commit:
+ * pass `removedAt: undefined` (the pending state). On successful
+ * data-cleanup: pass `removedAt` set and `error: undefined`. On
+ * cleanup failure: pass `removedAt: undefined` (preserves any prior
+ * timestamp from a partial success on a different replica) and the
+ * error message.
+ */
+type RecordKindRemovalParams = Readonly<{
+    graphId: string;
+    kindName: string;
+    entity: KindEntity;
+    schemaVersion: number;
+    attemptedAt: string;
+    /** ISO timestamp on success; undefined while pending or on failure. */
+    removedAt: string | undefined;
+    /** Error message on failure; undefined on success or while pending. */
+    error: string | undefined;
+}>;
+/**
+ * Transaction options.
+ */
+type TransactionOptions = Readonly<{
+    /** Transaction isolation level (if supported) */
+    isolationLevel?: "read_uncommitted" | "read_committed" | "repeatable_read" | "serializable";
+}>;
+/**
+ * Transaction backend — a backend scoped to a transaction.
+ *
+ * `commitSchemaVersion` and `setActiveVersion` are intentionally omitted:
+ * the atomicity / CAS guarantees of those primitives depend on
+ * dialect-specific write-locking (BEGIN IMMEDIATE on SQLite,
+ * `pg_advisory_xact_lock` on Postgres) acquired by the top-level
+ * backend wrappers, not the transaction itself. Calling them from a
+ * user-supplied `backend.transaction(...)` callback would bypass that
+ * locking and silently weaken the orphan-row crash window the primitive
+ * exists to eliminate. Schema commits go through the top-level backend
+ * methods only.
+ */
+type TransactionBackend = Omit<GraphBackend, "transaction" | "close" | "refreshStatistics" | "commitSchemaVersion" | "setActiveVersion">;
+/**
+ * The GraphBackend interface abstracts database operations.
+ *
+ * Implementations should provide:
+ * - SQLite backend via better-sqlite3 or libsql
+ * - PostgreSQL backend via pg or postgres
+ */
+type GraphBackend = Readonly<{
+    /** The SQL dialect */
+    dialect: SqlDialect;
+    /** Backend capabilities */
+    capabilities: BackendCapabilities;
+    /** Table names used by this backend (for query schema auto-derivation) */
+    tableNames?: SqlTableNames | undefined;
+    /**
+     * Optional fulltext strategy override. When present, both the compiler
+     * (for `$fulltext.matches()` in query builder) and backend-direct
+     * search paths use this instead of the dialect's default strategy —
+     * allowing a Postgres backend to ship pg_trgm, ParadeDB, pgroonga etc.
+     * When absent, the dialect's default strategy is used.
+     */
+    fulltextStrategy?: FulltextStrategy | undefined;
+    insertNode: (params: InsertNodeParams) => Promise<NodeRow>;
+    insertNodeNoReturn?: (params: InsertNodeParams) => Promise<void>;
+    insertNodesBatch?: (params: readonly InsertNodeParams[]) => Promise<void>;
+    insertNodesBatchReturning?: (params: readonly InsertNodeParams[]) => Promise<readonly NodeRow[]>;
+    updateNode: (params: UpdateNodeParams) => Promise<NodeRow>;
+    deleteNode: (params: DeleteNodeParams) => Promise<void>;
+    hardDeleteNode: (params: HardDeleteNodeParams) => Promise<void>;
+    getNode: (graphId: string, kind: string, id: string) => Promise<NodeRow | undefined>;
+    getNodes?: (graphId: string, kind: string, ids: readonly string[]) => Promise<readonly NodeRow[]>;
+    insertEdge: (params: InsertEdgeParams) => Promise<EdgeRow>;
+    insertEdgeNoReturn?: (params: InsertEdgeParams) => Promise<void>;
+    insertEdgesBatch?: (params: readonly InsertEdgeParams[]) => Promise<void>;
+    insertEdgesBatchReturning?: (params: readonly InsertEdgeParams[]) => Promise<readonly EdgeRow[]>;
+    updateEdge: (params: UpdateEdgeParams) => Promise<EdgeRow>;
+    deleteEdge: (params: DeleteEdgeParams) => Promise<void>;
+    hardDeleteEdge: (params: HardDeleteEdgeParams) => Promise<void>;
+    getEdge: (graphId: string, id: string) => Promise<EdgeRow | undefined>;
+    getEdges?: (graphId: string, ids: readonly string[]) => Promise<readonly EdgeRow[]>;
+    countEdgesFrom: (params: CountEdgesFromParams) => Promise<number>;
+    edgeExistsBetween: (params: EdgeExistsBetweenParams) => Promise<boolean>;
+    findEdgesConnectedTo: (params: FindEdgesConnectedToParams) => Promise<readonly EdgeRow[]>;
+    findNodesByKind: (params: FindNodesByKindParams) => Promise<readonly NodeRow[]>;
+    countNodesByKind: (params: CountNodesByKindParams) => Promise<number>;
+    findEdgesByKind: (params: FindEdgesByKindParams) => Promise<readonly EdgeRow[]>;
+    countEdgesByKind: (params: CountEdgesByKindParams) => Promise<number>;
+    insertUnique: (params: InsertUniqueParams) => Promise<void>;
+    deleteUnique: (params: DeleteUniqueParams) => Promise<void>;
+    checkUnique: (params: CheckUniqueParams) => Promise<UniqueRow | undefined>;
+    checkUniqueBatch?: (params: CheckUniqueBatchParams) => Promise<readonly UniqueRow[]>;
+    getActiveSchema: (graphId: string) => Promise<SchemaVersionRow | undefined>;
+    getSchemaVersion: (graphId: string, version: number) => Promise<SchemaVersionRow | undefined>;
+    /**
+     * Atomically inserts a new schema version and activates it as a single
+     * transactional unit, with optimistic compare-and-swap on the currently
+     * active version.
+     *
+     * - If `expected.kind === "active"` and the actual active version
+     *   differs, throws `StaleVersionError` (caller should refetch and
+     *   retry).
+     * - If a row already exists at `params.version` with the same
+     *   `schemaHash`, returns it idempotently — reactivating it if it was
+     *   left inactive by an earlier crashed commit.
+     * - If a row already exists at `params.version` with a different
+     *   `schemaHash`, throws `SchemaContentConflictError`.
+     *
+     * Requires `capabilities.transactions === true`. On non-transactional
+     * backends (e.g. Cloudflare D1, drizzle-orm/neon-http) this method
+     * throws `ConfigurationError` rather than running with degraded
+     * atomicity that would silently re-introduce the orphan-row crash
+     * window the primitive exists to eliminate.
+     */
+    commitSchemaVersion: (params: CommitSchemaVersionParams) => Promise<SchemaVersionRow>;
+    /**
+     * Atomically flips the active schema pointer to an existing version,
+     * with optimistic compare-and-swap on the currently active version.
+     * Used by `rollbackSchema` and any other "promote/demote existing
+     * version" workflow. Throws `StaleVersionError` on CAS mismatch and
+     * `MigrationError` if the target version row does not exist.
+     *
+     * Same transactional requirements as `commitSchemaVersion`.
+     */
+    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>;
+    upsertFulltext?: (params: UpsertFulltextParams) => Promise<void>;
+    deleteFulltext?: (params: DeleteFulltextParams) => Promise<void>;
+    /**
+     * Batched variant of `upsertFulltext`. Optional — callers fall back to
+     * per-row `upsertFulltext` when unset.
+     */
+    upsertFulltextBatch?: (params: UpsertFulltextBatchParams) => Promise<void>;
+    /**
+     * Batched variant of `deleteFulltext`. Optional — callers fall back to
+     * per-row `deleteFulltext` when unset.
+     */
+    deleteFulltextBatch?: (params: DeleteFulltextBatchParams) => Promise<void>;
+    fulltextSearch?: (params: FulltextSearchParams) => Promise<readonly FulltextSearchResult[]>;
+    /**
+     * Idempotently ensure ONLY the `typegraph_index_materializations`
+     * table exists — separate from `bootstrapTables` so that
+     * `materializeIndexes` doesn't pull in the full base-table DDL set
+     * just to access the status table.
+     *
+     * Why focused: `bootstrapTables` issues 20+ `CREATE TABLE / CREATE
+     * INDEX IF NOT EXISTS` statements covering every base table. Two
+     * concurrent calls (e.g. two replicas of the same `schema_doc` both
+     * starting up and calling `materializeIndexes`) race on
+     * Postgres SHARE locks and DEADLOCK. Restricting the ensure-step to
+     * the single status table eliminates the cross-table race entirely
+     * — concurrent `CREATE TABLE IF NOT EXISTS` for one specific table
+     * is well-behaved on Postgres.
+     */
+    ensureIndexMaterializationsTable?: () => Promise<void>;
+    /**
+     * Look up a recorded materialization for a declared index by its
+     * physical SQL index name. Returns `undefined` if no row exists.
+     */
+    getIndexMaterialization?: (indexName: string) => Promise<IndexMaterializationRow | undefined>;
+    /**
+     * Bulk variant of `getIndexMaterialization`: load every recorded
+     * materialization whose `indexName` (status key) is in `statusKeys`,
+     * in a single round-trip. Returned rows are unordered — callers index
+     * by `indexName`. Optional; consumers fall back to per-key
+     * `getIndexMaterialization` when unset.
+     */
+    getIndexMaterializations?: (statusKeys: readonly string[]) => Promise<readonly IndexMaterializationRow[]>;
+    /**
+     * Upsert a materialization attempt — success or failure. Failure rows
+     * preserve any prior `materializedAt` so the historical successful
+     * timestamp survives across error windows.
+     */
+    recordIndexMaterialization?: (params: RecordIndexMaterializationParams) => Promise<void>;
+    /**
+     * Bootstraps the per-deployment `typegraph_kind_removals` table so
+     * `store.removeKinds()` and `store.materializeRemovals()` can persist
+     * removal status. Mirrors the focused-bootstrap rationale documented
+     * on `ensureIndexMaterializationsTable` — the full `bootstrapTables`
+     * touches every base table and risks Postgres SHARE-lock deadlock
+     * under concurrent replica startup.
+     */
+    ensureKindRemovalsTable?: () => Promise<void>;
+    /**
+     * List graph-extension kind removals whose data-cleanup pass has not yet
+     * succeeded for this `graphId`. Returns rows with
+     * `removedAt: undefined`. Order is unspecified; callers materialize
+     * one-at-a-time and don't depend on it.
+     */
+    getPendingKindRemovals?: (graphId: string) => Promise<readonly KindRemovalRow[]>;
+    /**
+     * List ALL kind-removal rows for a `graphId` — pending and completed.
+     * Used by `materializeRemovals()` reconciliation to detect rows that
+     * are missing entirely (the `removeKinds()` crash window) versus
+     * already completed. Without this distinction the reconciler would
+     * have to upsert every expected historical removal on every call,
+     * churning `last_attempted_at` on rows that long since succeeded.
+     * Order is unspecified.
+     */
+    getAllKindRemovals?: (graphId: string) => Promise<readonly KindRemovalRow[]>;
+    /**
+     * Upsert a kind-removal status row. `removedAt: undefined` records
+     * the pending state at schema-commit time; `removedAt: <iso>`
+     * marks the data cleanup successful. The COALESCE rule on `removedAt`
+     * mirrors `recordIndexMaterialization` so a later failure doesn't
+     * clobber the historical successful timestamp from another replica.
+     */
+    recordKindRemoval?: (params: RecordKindRemovalParams) => Promise<void>;
+    /**
+     * Bootstraps the per-deployment `typegraph_reconciliation_markers`
+     * table so `materializeRemovals()` can persist reconciliation
+     * progress. Same focused-bootstrap rationale as the other status
+     * tables — full `bootstrapTables` risks Postgres SHARE-lock
+     * deadlock under concurrent replica startup.
+     */
+    ensureReconciliationMarkersTable?: () => Promise<void>;
+    /**
+     * Read the high-water mark schema version for which
+     * `materializeRemovals` reconciliation has already verified history
+     * for `graphId`. Returns `undefined` when no marker has been
+     * recorded yet. Used to skip already-checked transitions in the
+     * recovery walk.
+     */
+    getReconciliationMarker?: (graphId: string) => Promise<number | undefined>;
+    /**
+     * Persist the reconciliation high-water mark for `graphId`. Called
+     * after `materializeRemovals` completes a clean walk; subsequent
+     * calls walk only versions newer than this marker. Idempotent
+     * upsert by `graphId`.
+     */
+    setReconciliationMarker?: (graphId: string, version: number) => Promise<void>;
+    /**
+     * Hard-deletes all data for a graph (nodes, edges, uniques, embeddings, schema versions).
+     * Intended for import-replacement workflows. No hooks, no per-row logic.
+     */
+    clearGraph: (graphId: string) => Promise<void>;
+    /**
+     * Creates the base TypeGraph tables if they don't already exist.
+     *
+     * Called automatically by `createStoreWithSchema()` when a fresh database
+     * is detected. Users who manage DDL themselves via `createStore()` never
+     * hit this path.
+     */
+    bootstrapTables?: () => Promise<void>;
+    /**
+     * Refreshes the backend's query-planner statistics.
+     *
+     * Call this once after a large initial import or bulk backfill. Without
+     * up-to-date statistics, the planner can pick suboptimal execution plans
+     * — on PostgreSQL this is the difference between a 0.5ms and a 5ms
+     * forward traversal; on SQLite it's the difference between 0.9ms and
+     * 23ms fulltext search. Autovacuum / background statistics collection
+     * will catch up eventually, but calling this explicitly after a bulk
+     * load gives you correct latencies immediately.
+     *
+     * Implementations:
+     * - SQLite runs `ANALYZE`, which populates `sqlite_stat1`
+     * - PostgreSQL runs `ANALYZE` on the TypeGraph-managed tables
+     *
+     * Safe to call at any time; costs a few tens of milliseconds on the
+     * sizes this library is designed for.
+     */
+    refreshStatistics: () => Promise<void>;
+    execute: <T>(query: SQL) => Promise<readonly T[]>;
+    /** Execute pre-compiled SQL text with bound parameters. Available on sync SQLite and pg backends. */
+    executeRaw?: <T>(sqlText: string, params: readonly unknown[]) => Promise<readonly T[]>;
+    /** Compile a Drizzle SQL object to { sql, params } without executing. */
+    compileSql?: (query: SQL) => Readonly<{
+        sql: string;
+        params: readonly unknown[];
+    }>;
+    /**
+     * Execute a DDL statement that returns no rows (CREATE INDEX,
+     * CREATE TABLE, ALTER TABLE, etc.). Separate from `executeRaw`
+     * because some drivers (better-sqlite3) require `.run()` for DDL
+     * and `.all()` for queries — the ambiguity can't be resolved by
+     * inspecting the SQL string portably.
+     *
+     * Postgres path can use this for `CREATE INDEX CONCURRENTLY`, which
+     * cannot run inside a transaction. Implementations must execute the
+     * statement outside `transaction(...)`.
+     */
+    executeDdl?: (ddl: string) => Promise<void>;
+    transaction: <T>(fn: (tx: TransactionBackend) => Promise<T>, options?: TransactionOptions) => Promise<T>;
+    close: () => Promise<void>;
+}>;
+/**
+ * Parameters for inserting a unique constraint entry.
+ */
+type InsertUniqueParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    constraintName: string;
+    key: string;
+    nodeId: string;
+    concreteKind: string;
+}>;
+/**
+ * Parameters for deleting a unique constraint entry.
+ */
+type DeleteUniqueParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    constraintName: string;
+    key: string;
+}>;
+/**
+ * Parameters for checking a unique constraint.
+ */
+type CheckUniqueParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    constraintName: string;
+    key: string;
+    /** If true, also returns soft-deleted entries. Used by get-or-create operations. */
+    includeDeleted?: boolean;
+}>;
+/**
+ * Parameters for batch-checking unique constraints.
+ */
+type CheckUniqueBatchParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    constraintName: string;
+    keys: readonly string[];
+    /** If true, also returns soft-deleted entries. Used by get-or-create operations. */
+    includeDeleted?: boolean;
+}>;
+/**
+ * The caller's claim about the currently-active schema version, used as
+ * the optimistic compare-and-swap guard for `commitSchemaVersion`.
+ *
+ * - `{ kind: "initial" }` — caller is committing the first-ever version
+ *   for this graph and asserts no active version exists yet.
+ * - `{ kind: "active", version: N }` — caller observed version N as
+ *   active and is committing version N+1 against that baseline. The
+ *   commit fails with `StaleVersionError` if some other writer has
+ *   advanced or rolled back the pointer in the meantime.
+ *
+ * Tagged-union form (rather than a magic `version: 0` sentinel) because
+ * the two cases have materially different semantics: the initial path
+ * skips the "deactivate prior" UPDATE, and the no-active-row state is
+ * a *valid* expected state, not an out-of-band signal.
+ */
+type CommitSchemaVersionExpected = Readonly<{
+    kind: "initial";
+}> | Readonly<{
+    kind: "active";
+    version: number;
+}>;
+/**
+ * Parameters for `commitSchemaVersion`.
+ */
+type CommitSchemaVersionParams = Readonly<{
+    graphId: string;
+    /** CAS guard — see `CommitSchemaVersionExpected`. */
+    expected: CommitSchemaVersionExpected;
+    /** The new version to insert and activate. */
+    version: number;
+    schemaHash: string;
+    schemaDoc: SerializedSchema;
+}>;
+/**
+ * Parameters for `setActiveVersion`.
+ *
+ * Flips the active pointer from `expected` to `version` for an existing
+ * row. CAS prevents overwriting a concurrent rollback or commit.
+ */
+type SetActiveVersionParams = Readonly<{
+    graphId: string;
+    /** CAS guard. Same semantics as `commitSchemaVersion.expected`. */
+    expected: CommitSchemaVersionExpected;
+    /** The version to mark active. Must already exist. */
+    version: number;
+}>;
+/**
+ * Parameters for counting edges from a source node.
+ */
+type CountEdgesFromParams = Readonly<{
+    graphId: string;
+    edgeKind: string;
+    fromKind: string;
+    fromId: string;
+    /** If true, only count edges where valid_to IS NULL */
+    activeOnly?: boolean;
+}>;
+/**
+ * Parameters for checking if an edge exists between two nodes.
+ */
+type EdgeExistsBetweenParams = Readonly<{
+    graphId: string;
+    edgeKind: string;
+    fromKind: string;
+    fromId: string;
+    toKind: string;
+    toId: string;
+}>;
+/**
+ * Parameters for finding edges connected to a node.
+ */
+type FindEdgesConnectedToParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    nodeId: string;
+}>;
+/**
+ * Parameters for finding nodes by kind.
+ */
+type FindNodesByKindParams = Readonly<{
+    graphId: string;
+    kind: string;
+    /** Max rows to return. */
+    limit?: number;
+    /** Offset. Present for backward compat; rebuild uses `after` instead. */
+    offset?: number;
+    /** If true, exclude deleted nodes. Default true. */
+    excludeDeleted?: boolean;
+    /** Temporal mode for filtering by validity period. */
+    temporalMode?: TemporalMode;
+    /** Timestamp for "current" and "asOf" temporal modes. */
+    asOf?: string;
+    /**
+     * Stable ordering for keyset pagination. Default: "created_at" (existing
+     * behavior). Rebuild should use "id" for iteration that is stable under
+     * concurrent writes and shared timestamps.
+     */
+    orderBy?: "id" | "created_at";
+    /**
+     * Keyset cursor. Returns rows strictly greater (by `orderBy`) than this
+     * value. When `orderBy: "id"`, compared lexicographically. Mutually
+     * exclusive with `offset` — callers pick one.
+     */
+    after?: string;
+}>;
+/**
+ * Parameters for counting nodes by kind.
+ */
+type CountNodesByKindParams = Readonly<{
+    graphId: string;
+    kind: string;
+    /** If true, exclude deleted nodes. Default true. */
+    excludeDeleted?: boolean;
+    /** Temporal mode for filtering by validity period. */
+    temporalMode?: TemporalMode;
+    /** Timestamp for "current" and "asOf" temporal modes. */
+    asOf?: string;
+}>;
+/**
+ * Parameters for finding edges by kind.
+ */
+type FindEdgesByKindParams = Readonly<{
+    graphId: string;
+    kind: string;
+    fromKind?: string;
+    fromId?: string;
+    toKind?: string;
+    toId?: string;
+    limit?: number;
+    offset?: number;
+    /** If true, exclude deleted edges. Default true. */
+    excludeDeleted?: boolean;
+    /** Temporal mode for filtering by validity period. */
+    temporalMode?: TemporalMode;
+    /** Timestamp for "current" and "asOf" temporal modes. */
+    asOf?: string;
+}>;
+/**
+ * Parameters for counting edges by kind.
+ */
+type CountEdgesByKindParams = Readonly<{
+    graphId: string;
+    kind: string;
+    fromKind?: string;
+    fromId?: string;
+    toKind?: string;
+    toId?: string;
+    /** If true, exclude deleted edges. Default true. */
+    excludeDeleted?: boolean;
+    /** Temporal mode for filtering by validity period. */
+    temporalMode?: TemporalMode;
+    /** Timestamp for "current" and "asOf" temporal modes. */
+    asOf?: string;
+}>;
+
+/**
+ * Query AST types.
+ *
+ * Defines the abstract syntax tree for TypeGraph queries.
+ * This portable representation can be compiled to SQL (today)
+ * or other query languages (Cypher, SPARQL) in the future.
+ */
+
+/**
+ * A field reference in a predicate.
+ */
+type FieldRef = Readonly<{
+    __type: "field_ref";
+    alias: string;
+    path: readonly string[];
+    jsonPointer?: JsonPointer | undefined;
+    valueType?: ValueType | undefined;
+    elementType?: ValueType | undefined;
+}>;
+/**
+ * A literal value in a predicate.
+ */
+type LiteralValue = Readonly<{
+    __type: "literal";
+    value: string | number | boolean;
+    valueType?: ValueType | undefined;
+}>;
+/**
+ * A parameter reference for prepared queries.
+ *
+ * Used in place of a literal value to create parameterized queries
+ * that can be executed multiple times with different bindings.
+ */
+type ParameterRef = Readonly<{
+    __type: "parameter";
+    name: string;
+    valueType?: ValueType | undefined;
+}>;
+/**
+ * Supported value types for predicates.
+ */
+type ValueType = "string" | "number" | "boolean" | "date" | "array" | "object" | "embedding" | "unknown";
+/**
+ * Comparison operators.
+ */
+type ComparisonOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "notIn";
+/**
+ * String operators.
+ */
+type StringOp = "contains" | "startsWith" | "endsWith" | "like" | "ilike";
+/**
+ * A comparison predicate.
+ */
+type ComparisonPredicate = Readonly<{
+    __type: "comparison";
+    op: ComparisonOp;
+    left: FieldRef;
+    right: LiteralValue | LiteralValue[] | ParameterRef;
+}>;
+/**
+ * A string predicate.
+ */
+type StringPredicate = Readonly<{
+    __type: "string_op";
+    op: StringOp;
+    field: FieldRef;
+    pattern: string | ParameterRef;
+}>;
+/**
+ * A null check predicate.
+ */
+type NullPredicate = Readonly<{
+    __type: "null_check";
+    op: NullCheckOp;
+    field: FieldRef;
+}>;
+/**
+ * A between predicate.
+ */
+type BetweenPredicate = Readonly<{
+    __type: "between";
+    field: FieldRef;
+    lower: LiteralValue | ParameterRef;
+    upper: LiteralValue | ParameterRef;
+}>;
+/**
+ * Array operators.
+ */
+type ArrayOp = "contains" | "containsAll" | "containsAny" | "isEmpty" | "isNotEmpty" | "lengthEq" | "lengthGt" | "lengthGte" | "lengthLt" | "lengthLte";
+/**
+ * An array predicate.
+ */
+type ArrayPredicate = Readonly<{
+    __type: "array_op";
+    op: ArrayOp;
+    field: FieldRef;
+    values?: readonly LiteralValue[];
+    length?: number;
+}>;
+/**
+ * Object operators.
+ */
+type ObjectOp = "hasKey" | "hasPath" | "pathEquals" | "pathContains" | "pathIsNull" | "pathIsNotNull";
+/**
+ * An object/JSON predicate.
+ */
+type ObjectPredicate = Readonly<{
+    __type: "object_op";
+    op: ObjectOp;
+    field: FieldRef;
+    pointer: JsonPointer;
+    value?: LiteralValue;
+    valueType?: ValueType;
+    elementType?: ValueType;
+}>;
+/**
+ * Logical AND predicate.
+ */
+type AndPredicate = Readonly<{
+    __type: "and";
+    predicates: readonly PredicateExpression[];
+}>;
+/**
+ * Logical OR predicate.
+ */
+type OrPredicate = Readonly<{
+    __type: "or";
+    predicates: readonly PredicateExpression[];
+}>;
+/**
+ * Logical NOT predicate.
+ */
+type NotPredicate = Readonly<{
+    __type: "not";
+    predicate: PredicateExpression;
+}>;
+/**
+ * An aggregate comparison predicate (for HAVING clauses).
+ */
+type AggregateComparisonPredicate = Readonly<{
+    __type: "aggregate_comparison";
+    op: ComparisonOp;
+    aggregate: AggregateExpr;
+    value: LiteralValue;
+}>;
+/**
+ * An EXISTS subquery predicate.
+ * Tests whether the subquery returns any rows.
+ */
+type ExistsSubquery = Readonly<{
+    __type: "exists";
+    subquery: QueryAst;
+    negated: boolean;
+}>;
+/**
+ * An IN subquery predicate.
+ * Tests whether a field value is in the subquery results.
+ */
+type InSubquery = Readonly<{
+    __type: "in_subquery";
+    field: FieldRef;
+    subquery: QueryAst;
+    negated: boolean;
+}>;
+/**
+ * Vector similarity metric types.
+ */
+type VectorMetricType = "cosine" | "l2" | "inner_product";
+/**
+ * A vector similarity predicate.
+ * Finds nodes with embeddings similar to the query embedding.
+ *
+ * This predicate affects query execution by:
+ * - Joining with the embeddings table
+ * - Adding ORDER BY distance (ascending)
+ * - Applying LIMIT (top k results)
+ * - Optionally filtering by minimum score
+ */
+type VectorSimilarityPredicate = Readonly<{
+    __type: "vector_similarity";
+    /** The embedding field reference */
+    field: FieldRef;
+    /** The query embedding to compare against */
+    queryEmbedding: readonly number[];
+    /** Similarity metric to use */
+    metric: VectorMetricType;
+    /** Maximum number of results to return */
+    limit: number;
+    /** Optional minimum similarity score (0-1 for cosine) */
+    minScore?: number;
+}>;
+
+/**
+ * A fulltext MATCH predicate.
+ *
+ * Finds nodes whose combined searchable content matches the query. Affects
+ * query execution by joining with the fulltext table, adding an ORDER BY
+ * on relevance rank (descending), and applying a LIMIT (top k).
+ */
+type FulltextMatchPredicate = Readonly<{
+    __type: "fulltext_match";
+    /**
+     * Reserved for forward compatibility with per-field fulltext dispatch.
+     * Today only `field.alias` is consumed: the MATCH always targets the
+     * combined `content` column, so `field.path` is a synthetic
+     * `["$fulltext"]` marker rather than a real props path. Future
+     * strategies (per-field indexes, `setweight()`-style boosts) can use
+     * the full `FieldRef` without breaking the AST shape.
+     */
+    field: FieldRef;
+    /** The user-supplied query string. */
+    query: string;
+    /** Parse mode for the query string. Default: "websearch". */
+    mode: FulltextQueryMode;
+    /** Language override for query parsing. */
+    language?: string;
+    /** Maximum number of results to return. */
+    limit: number;
+    /** Minimum relevance to include (backend-native units). */
+    minScore?: number;
+}>;
+/**
+ * Fusion options for hybrid (vector + fulltext) queries.
+ *
+ * Shared between:
+ * - Query-builder path: `QueryBuilder.fuseWith()` stores this on `QueryAst`.
+ * - Store path: `store.search.hybrid(kind, { fusion })` accepts the same shape.
+ *
+ * Only applied when the query contains both a vector and a fulltext
+ * predicate. Defaults (when omitted): RRF with k=60 and equal weights.
+ */
+type HybridFusionOptions = Readonly<{
+    /** RRF is the only currently supported fusion method. */
+    method?: "rrf";
+    /** RRF constant. The classic value is 60. */
+    k?: number;
+    /** Per-source weights. Default: { vector: 1, fulltext: 1 }. */
+    weights?: Readonly<{
+        vector?: number;
+        fulltext?: number;
+    }>;
+}>;
+/**
+ * All predicate expression types.
+ */
+type PredicateExpression = ComparisonPredicate | StringPredicate | NullPredicate | BetweenPredicate | ArrayPredicate | ObjectPredicate | AndPredicate | OrPredicate | NotPredicate | AggregateComparisonPredicate | ExistsSubquery | InSubquery | VectorSimilarityPredicate | FulltextMatchPredicate;
+/**
+ * The starting point of a query (the FROM clause).
+ */
+type QueryStart = Readonly<{
+    alias: string;
+    kinds: readonly string[];
+    includeSubClasses: boolean;
+}>;
+/**
+ * Direction of edge traversal.
+ */
+type TraversalDirection = "out" | "in";
+/**
+ * Traversal ontology expansion behavior.
+ *
+ * - `"none"` — follow only the exact edge kind specified
+ * - `"implying"` — also follow edge kinds that imply the specified kind (subClassOf)
+ * - `"inverse"` — also follow the ontological inverse edge kind (inverseOf)
+ * - `"all"` — follow both implying and inverse expansions
+ */
+type TraversalExpansion = "none" | "implying" | "inverse" | "all";
+/**
+ * Cycle handling policy for recursive traversals.
+ */
+type RecursiveCyclePolicy = "prevent" | "allow";
+/**
+ * Variable-length traversal specification for recursive graph traversals.
+ */
+type VariableLengthSpec = Readonly<{
+    /** Minimum number of hops before including results (default: 1) */
+    minDepth: number;
+    /** Maximum number of hops (-1 = unlimited, default: -1) */
+    maxDepth: number;
+    /**
+     * Cycle handling mode.
+     *
+     * - "prevent": Track visited nodes per path and reject revisits
+     * - "allow": Skip cycle checks (faster, may revisit nodes)
+     */
+    cyclePolicy: RecursiveCyclePolicy;
+    /** Optional column alias for projected traversal path array */
+    pathAlias?: string;
+    /** Optional column alias for projected traversal depth */
+    depthAlias?: string;
+}>;
+/**
+ * A traversal step in the query.
+ */
+type Traversal = Readonly<{
+    edgeAlias: string;
+    edgeKinds: readonly string[];
+    /**
+     * Edge kinds traversed in the opposite direction.
+     *
+     * Populated when query options request inverse/symmetric expansion.
+     */
+    inverseEdgeKinds?: readonly string[];
+    direction: TraversalDirection;
+    nodeAlias: string;
+    nodeKinds: readonly string[];
+    joinFromAlias: string;
+    joinEdgeField: "from_id" | "to_id";
+    /** If true, use LEFT JOIN instead of INNER JOIN (optional match) */
+    optional: boolean;
+    /** Variable-length traversal configuration (for recursive CTEs) */
+    variableLength?: VariableLengthSpec;
+}>;
+/**
+ * Supported aggregate functions.
+ */
+type AggregateFunction = "count" | "countDistinct" | "sum" | "avg" | "min" | "max";
+/**
+ * An aggregate expression.
+ */
+type AggregateExpr = Readonly<{
+    __type: "aggregate";
+    function: AggregateFunction;
+    field: FieldRef;
+}>;
+/**
+ * A GROUP BY specification.
+ */
+type GroupBySpec = Readonly<{
+    fields: readonly FieldRef[];
+}>;
+/**
+ * A projected field in the SELECT clause.
+ * Can be either a direct field reference or an aggregate expression.
+ */
+type ProjectedField = Readonly<{
+    outputName: string;
+    source: FieldRef | AggregateExpr;
+    /** Override the CTE alias for this field (used for edge fields in node CTEs) */
+    cteAlias?: string;
+}>;
+/**
+ * The projection (SELECT) clause.
+ */
+type Projection = Readonly<{
+    fields: readonly ProjectedField[];
+}>;
+/**
+ * A selectively projected field for optimized queries.
+ *
+ * Used when the select callback only accesses specific fields,
+ * allowing the compiler to generate optimized SQL that fetches
+ * only those fields instead of the full props blob.
+ */
+type SelectiveField = Readonly<{
+    /** The alias (node or edge) this field belongs to */
+    alias: string;
+    /** The field name (e.g., "email", "name", "id") */
+    field: string;
+    /** The output column name in the result (e.g., "p_email") */
+    outputName: string;
+    /** True if this is a system field (id, kind, etc.), false for props */
+    isSystemField: boolean;
+    /**
+     * Optional value type for props fields.
+     *
+     * When present, the compiler can use type-aware JSON extraction
+     * (e.g. numeric/date casts) to better match predicate compilation
+     * and enable expression index coverage.
+     */
+    valueType?: ValueType | undefined;
+}>;
+/**
+ * Null ordering preference.
+ */
+type NullOrdering = "first" | "last";
+/**
+ * Sort direction.
+ */
+type SortDirection = "asc" | "desc";
+/**
+ * An ordering specification.
+ */
+type OrderSpec = Readonly<{
+    field: FieldRef;
+    direction: SortDirection;
+    nulls?: NullOrdering;
+}>;
+/**
+ * A predicate applied to a specific node or edge alias.
+ */
+type NodePredicate = Readonly<{
+    targetAlias: string;
+    /** Whether this predicate targets a node or edge. Defaults to "node". */
+    targetType?: KindEntity;
+    expression: PredicateExpression;
+}>;
+/**
+ * Temporal query options.
+ */
+type TemporalOptions = Readonly<{
+    mode: TemporalMode;
+    asOf?: string;
+}>;
+/**
+ * The complete query AST.
+ */
+type QueryAst = Readonly<{
+    /** The graph ID this query is for (used for subqueries) */
+    graphId?: string;
+    start: QueryStart;
+    traversals: readonly Traversal[];
+    predicates: readonly NodePredicate[];
+    projection: Projection;
+    temporalMode: TemporalOptions;
+    orderBy?: readonly OrderSpec[];
+    limit?: number;
+    offset?: number;
+    /** GROUP BY specification for aggregate queries */
+    groupBy?: GroupBySpec;
+    /** HAVING clause - predicates applied after GROUP BY */
+    having?: PredicateExpression;
+    /**
+     * Selective fields for optimized queries.
+     * When present, the compiler generates SQL that only fetches these specific
+     * fields instead of the full props blob, enabling covered index usage.
+     */
+    selectiveFields?: readonly SelectiveField[];
+    /** Fusion options for hybrid queries. Ignored unless both predicates present. */
+    fusion?: HybridFusionOptions;
+}>;
+/**
+ * Set operation types for combining queries.
+ */
+type SetOperationType = "union" | "unionAll" | "intersect" | "except";
+/**
+ * A set operation combining two queries.
+ */
+type SetOperation = Readonly<{
+    __type: "set_operation";
+    operator: SetOperationType;
+    left: ComposableQuery;
+    right: ComposableQuery;
+    orderBy?: readonly OrderSpec[];
+    limit?: number;
+    offset?: number;
+}>;
+/**
+ * A composable query - either a base query or a set operation.
+ */
+type ComposableQuery = QueryAst | SetOperation;
+
+type IndexScope = 
+/**
+ * Prefix index keys with `(graph_id, kind)` (nodes) or `(graph_id, kind)` (edges).
+ *
+ * This matches TypeGraph queries which always filter on `graph_id` and `kind`
+ * (often as `IN (...)` due to ontology expansion).
+ */
+"graphAndKind"
+/**
+ * Prefix index keys with `graph_id` only.
+ */
+ | "graph"
+/**
+ * Do not prefix index keys with TypeGraph system columns.
+ */
+ | "none";
+type IndexWhereOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "notIn";
+type IndexWhereExpression = Readonly<{
+    __type: "index_where_and";
+    predicates: readonly IndexWhereExpression[];
+}> | Readonly<{
+    __type: "index_where_or";
+    predicates: readonly IndexWhereExpression[];
+}> | Readonly<{
+    __type: "index_where_not";
+    predicate: IndexWhereExpression;
+}> | Readonly<{
+    __type: "index_where_comparison";
+    left: IndexWhereOperand;
+    op: IndexWhereOp;
+    right: IndexWhereLiteral | readonly IndexWhereLiteral[];
+}> | Readonly<{
+    __type: "index_where_null_check";
+    operand: IndexWhereOperand;
+    op: NullCheckOp;
+}>;
+type IndexWhereOperand = Readonly<{
+    __type: "index_operand_system";
+    column: SystemColumnName;
+    valueType: ValueType | undefined;
+}> | Readonly<{
+    __type: "index_operand_prop";
+    field: string;
+    valueType: ValueType | undefined;
+}>;
+type IndexWhereLiteral = Readonly<{
+    __type: "index_where_literal";
+    value: string | number | boolean;
+    valueType: ValueType;
+}>;
+type IndexWhereComparableValue<T> = NonNullable<T> extends string ? string : NonNullable<T> extends number ? number : NonNullable<T> extends boolean ? boolean : NonNullable<T> extends Date ? Date | string : never;
+type IndexWhereFieldBuilder<T> = Readonly<{
+    eq: (value: IndexWhereComparableValue<T>) => IndexWhereExpression;
+    neq: (value: IndexWhereComparableValue<T>) => IndexWhereExpression;
+    gt: (value: IndexWhereComparableValue<T>) => IndexWhereExpression;
+    gte: (value: IndexWhereComparableValue<T>) => IndexWhereExpression;
+    lt: (value: IndexWhereComparableValue<T>) => IndexWhereExpression;
+    lte: (value: IndexWhereComparableValue<T>) => IndexWhereExpression;
+    in: (values: readonly IndexWhereComparableValue<T>[]) => IndexWhereExpression;
+    notIn: (values: readonly IndexWhereComparableValue<T>[]) => IndexWhereExpression;
+    isNull: () => IndexWhereExpression;
+    isNotNull: () => IndexWhereExpression;
+}>;
+type NodeIndexWhereBuilder<N extends NodeType> = Readonly<{
+    graphId: IndexWhereFieldBuilder<string>;
+    kind: IndexWhereFieldBuilder<string>;
+    id: IndexWhereFieldBuilder<string>;
+    deletedAt: IndexWhereFieldBuilder<string | undefined>;
+    validFrom: IndexWhereFieldBuilder<string | undefined>;
+    validTo: IndexWhereFieldBuilder<string | undefined>;
+    createdAt: IndexWhereFieldBuilder<string>;
+    updatedAt: IndexWhereFieldBuilder<string>;
+    version: IndexWhereFieldBuilder<number>;
+} & {
+    [K in keyof z.infer<N["schema"]>]-?: IndexWhereFieldBuilder<z.infer<N["schema"]>[K]>;
+}>;
+type EdgeIndexWhereBuilder<E extends AnyEdgeType> = Readonly<{
+    graphId: IndexWhereFieldBuilder<string>;
+    kind: IndexWhereFieldBuilder<string>;
+    id: IndexWhereFieldBuilder<string>;
+    fromKind: IndexWhereFieldBuilder<string>;
+    fromId: IndexWhereFieldBuilder<string>;
+    toKind: IndexWhereFieldBuilder<string>;
+    toId: IndexWhereFieldBuilder<string>;
+    deletedAt: IndexWhereFieldBuilder<string | undefined>;
+    validFrom: IndexWhereFieldBuilder<string | undefined>;
+    validTo: IndexWhereFieldBuilder<string | undefined>;
+    createdAt: IndexWhereFieldBuilder<string>;
+    updatedAt: IndexWhereFieldBuilder<string>;
+} & {
+    [K in keyof z.infer<E["schema"]>]-?: IndexWhereFieldBuilder<z.infer<E["schema"]>[K]>;
+}>;
+type IndexWhereInput<Builder> = IndexWhereExpression | ((where: Builder) => IndexWhereExpression);
+type NonEmptyJsonPointerFor<T> = Exclude<JsonPointerFor<T>, "">;
+type NonEmptyJsonPointerSegmentsFor<T> = Exclude<JsonPointerSegmentsFor<T>, readonly []>;
+type IndexFieldInput<T> = (keyof T & string) | NonEmptyJsonPointerFor<T> | NonEmptyJsonPointerSegmentsFor<T> | JsonPointer;
+type NodeIndexConfig<N extends NodeType> = Readonly<{
+    fields: readonly [
+        IndexFieldInput<z.infer<N["schema"]>>,
+        ...IndexFieldInput<z.infer<N["schema"]>>[]
+    ];
+    coveringFields?: readonly IndexFieldInput<z.infer<N["schema"]>>[] | undefined;
+    unique?: boolean | undefined;
+    name?: string | undefined;
+    scope?: IndexScope | undefined;
+    where?: IndexWhereInput<NodeIndexWhereBuilder<N>> | undefined;
+}>;
+type EdgeIndexDirection = "out" | "in" | "none";
+type EdgeIndexConfig<E extends AnyEdgeType> = Readonly<{
+    fields: readonly [
+        IndexFieldInput<z.infer<E["schema"]>>,
+        ...IndexFieldInput<z.infer<E["schema"]>>[]
+    ];
+    coveringFields?: readonly IndexFieldInput<z.infer<E["schema"]>>[] | undefined;
+    unique?: boolean | undefined;
+    name?: string | undefined;
+    scope?: IndexScope | undefined;
+    /**
+     * Optional direction hint to prefix edge indexes with the join key that
+     * TypeGraph traversal queries use (`from_id` for out, `to_id` for in).
+     */
+    direction?: EdgeIndexDirection | undefined;
+    where?: IndexWhereInput<EdgeIndexWhereBuilder<E>> | undefined;
+}>;
+/**
+ * Where an index declaration originated.
+ *
+ * - `compile-time`: declared via `defineNodeIndex` / `defineEdgeIndex` and
+ *   threaded through `defineGraph({ indexes })`. This is the default and is
+ *   omitted from the canonical schema document so legacy graphs hash
+ *   byte-identically.
+ * - `runtime`: produced by a graph extension. Always emitted explicitly
+ *   so the loader can re-route the declaration through the extension
+ *   compiler on restart.
+ */
+type IndexOrigin = "compile-time" | "runtime";
+/**
+ * Common shape shared by node and edge index declarations.
+ *
+ * `IndexDeclaration` is the canonical, JSON-serializable representation of
+ * an index that flows through `GraphDef.indexes` and
+ * `SerializedSchema.indexes`. It carries everything the DDL compiler and
+ * the Drizzle schema factories need to generate index SQL — the same
+ * value can come from a typed builder (`defineNodeIndex` /
+ * `defineEdgeIndex`) or be reconstructed from a graph extension on
+ * restart.
+ */
+type IndexDeclarationBase = Readonly<{
+    /** Unique index name (used in DDL and as the diffing identity key). */
+    name: string;
+    /**
+     * Where this declaration originated.
+     *
+     * `undefined` is the canonical representation of `"compile-time"` —
+     * the default origin is omitted from the serialized form so legacy
+     * graphs (no `indexes` slice) hash byte-identically with new graphs
+     * that declare only compile-time indexes.
+     */
+    origin?: IndexOrigin;
+    fields: readonly JsonPointer[];
+    fieldValueTypes: readonly (ValueType | undefined)[];
+    coveringFields: readonly JsonPointer[];
+    coveringFieldValueTypes: readonly (ValueType | undefined)[];
+    unique: boolean;
+    scope: IndexScope;
+    where: IndexWhereExpression | undefined;
+}>;
+type NodeIndexDeclaration = IndexDeclarationBase & Readonly<{
+    entity: "node";
+    kind: string;
+}>;
+type EdgeIndexDeclaration = IndexDeclarationBase & Readonly<{
+    entity: "edge";
+    kind: string;
+    direction: EdgeIndexDirection;
+}>;
+/**
+ * Distance metric for vector similarity. Mirrors `EmbeddingMetric` from
+ * `core/embedding.ts` (re-exported here as part of the index surface).
+ */
+type VectorIndexMetric = "cosine" | "l2" | "inner_product";
+/**
+ * Vector index implementation. `none` is a declarative opt-out: the
+ * declaration carries shape metadata for tooling but `materializeIndexes`
+ * skips the DDL.
+ */
+type VectorIndexImplementation = "hnsw" | "ivfflat" | "none";
+/**
+ * Vector-index parameters. Concrete defaults are applied at the
+ * `embedding(...)` brand boundary; this carries them onto the
+ * declaration so the materializer / signature / drift detection have
+ * everything they need without re-resolving from the brand.
+ */
+type VectorIndexParams = Readonly<{
+    /** HNSW: max connections per layer. */
+    m: number;
+    /** HNSW: build-time search depth. */
+    efConstruction: number;
+    /** IVFFlat: number of inverted lists. `undefined` when not IVFFlat. */
+    lists: number | undefined;
+}>;
+/**
+ * Vector index declaration. Auto-derived from `embedding()` brands at
+ * `defineGraph()` time and explicitly buildable via `defineVectorIndex`.
+ *
+ * Identity key is `(kind, fieldPath)` — v1 allows at most one vector
+ * index per (kind, field) pair. The `name` field is generated
+ * deterministically from this tuple plus the metric so consumers don't
+ * accidentally collide vector index names with relational indexes.
+ *
+ * `unique` / `scope` / `where` from the relational base are NOT
+ * supported on vector — pgvector / sqlite-vec don't implement them.
+ */
+type VectorIndexDeclaration = Readonly<{
+    entity: "vector";
+    /** Index name (also the physical identity key in the materialization status table). */
+    name: string;
+    origin?: IndexOrigin;
+    /** Node kind the embedding lives on. */
+    kind: string;
+    /** JSON-pointer-style field path for the embedding inside the node's props. */
+    fieldPath: string;
+    /** Embedding dimensionality. */
+    dimensions: number;
+    /** Distance metric. */
+    metric: VectorIndexMetric;
+    /** Index implementation. */
+    indexType: VectorIndexImplementation;
+    /** Concrete index parameters. */
+    indexParams: VectorIndexParams;
+}>;
+/**
+ * Relational subset of `IndexDeclaration` — the variants that emit
+ * `CREATE INDEX` DDL via `generateIndexDDL`. Used to narrow input
+ * types in the relational DDL / serializer / migration code paths
+ * that don't apply to vector indexes (which use a different
+ * materialization primitive on the backend).
+ */
+type RelationalIndexDeclaration = NodeIndexDeclaration | EdgeIndexDeclaration;
+/**
+ * A serializable index declaration that flows through `GraphDef.indexes`
+ * and `SerializedSchema.indexes`.
+ *
+ * Discriminated by `entity`. Everything is JSON round-trippable so a
+ * declaration produced by `defineNodeIndex` and a declaration
+ * reconstructed from a stored schema document compile to byte-identical
+ * SQL.
+ */
+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 JsonPointerFor as $, type AggregateExpr as A, type BackendCapabilities as B, type FieldRef as C, type ComparisonOp as D, type EdgeIndexConfig as E, type FulltextStrategy as F, type GraphBackend as G, type AggregateComparisonPredicate as H, type IndexDeclaration as I, type JsonPointer as J, type CommitSchemaVersionExpected as K, type CommitSchemaVersionParams as L, type MetaEdge as M, type NodeIndexConfig as N, type OntologyRelation as O, DEFAULT_SQL_SCHEMA as P, type QueryAst as Q, type RelationalIndexDeclaration as R, type SerializedNodeDef as S, type DeleteFulltextBatchParams as T, type FulltextBatchRow as U, type VectorIndexDeclaration as V, type FulltextCapabilities as W, type FulltextQueryMode as X, type FulltextSearchParams as Y, type FulltextSearchResult as Z, type HybridFusionOptions as _, type EdgeIndexDeclaration as a, type JsonPointerInput as a0, type JsonPointerSegment as a1, type JsonPointerSegments as a2, type JsonPointerSegmentsFor as a3, MAX_JSON_POINTER_DEPTH as a4, type MetaEdgeProperties as a5, type OrderSpec as a6, type ParameterRef as a7, type ResolveJsonPointer as a8, type ResolveJsonPointerSegments as a9, type NodeRow as aA, type SelectiveField as aB, type ComposableQuery as aC, type SetOperationType as aD, type SetOperation as aE, type VectorMetric as aF, type SetActiveVersionParams as aa, type SortDirection as ab, type SqlSchema as ac, type SqlTableNames as ad, type TransactionBackend as ae, type TraversalExpansion as af, type UpsertFulltextBatchParams as ag, type VectorCapabilities as ah, createSqlSchema as ai, fts5Strategy as aj, isMetaEdge as ak, joinJsonPointers as al, jsonPointer as am, normalizeJsonPointer as an, parseJsonPointer as ao, tsvectorStrategy as ap, type ValueType as aq, type PredicateExpression as ar, type VectorMetricType as as, type Traversal as at, type NodePredicate as au, type ProjectedField as av, type GroupBySpec as aw, type RecursiveCyclePolicy as ax, type TraversalDirection as ay, type EdgeRow as az, type NodeIndexDeclaration as b, type IndexWhereExpression as c, type SerializedEdgeDef as d, type SerializedMetaEdge as e, type SerializedOntologyRelation as f, type SerializedClosures as g, type SerializedSchema as h, type SchemaHash as i, type JsonSchema as j, type SerializedOntology as k, type SerializedUniqueConstraint as l, type SqlDialect as m, type EdgeIndexDirection as n, type EdgeIndexWhereBuilder as o, type IndexOrigin as p, type IndexScope as q, type IndexWhereFieldBuilder as r, type IndexWhereInput as s, type NodeIndexWhereBuilder as t, type SystemColumnName as u, type VectorIndexImplementation as v, type VectorIndexMetric as w, type VectorIndexParams as x, type SchemaVersionRow as y, type InferenceType as z };