@nicia-ai/typegraph 0.1.0

package/dist/store-60Lcfi0w.d.ts

@@ -0,0 +1,2263 @@
+import { G as GraphBackend, S as SchemaVersionRow } from './types-CjZ7g_7v.js';
+import { N as NodeType, E as EdgeType, p as NodeRegistration, h as EdgeRegistration, D as DeleteBehavior, T as TemporalMode, i as EdgeTypeWithEndpoints, G as GraphDefaults, A as AnyEdgeType, n as NodeId, V as ValueType, P as PredicateExpression, z as VectorMetricType, Q as QueryAst, J as JsonPointer, F as FieldRef, k as JsonPointerInput, B as Traversal, H as NodePredicate, I as ProjectedField, O as OrderSpec, K as GroupBySpec, L as TraversalDirection, c as AggregateExpr, W as ComposableQuery, X as SetOperationType, Y as SetOperation, S as SortDirection, r as UniquenessScope, f as Collation, e as Cardinality, j as EndpointExistence } from './ast-BVyihVbP.js';
+import { SQL } from 'drizzle-orm';
+import { z } from 'zod';
+import { S as SqlDialect } from './types-BRzHlhKC.js';
+
+/** 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;
+
+/**
+ * Embedding type for vector search.
+ *
+ * Creates a Zod-compatible schema for vector embeddings with
+ * dimension validation and metadata for query compilation.
+ */
+
+/**
+ * Symbol used to brand embedding values at the type level.
+ * This allows TypeScript to distinguish embedding arrays from regular
+ * number arrays in the query builder type system.
+ */
+declare const EMBEDDING_BRAND: unique symbol;
+/**
+ * Branded embedding type for type-level distinction.
+ * At runtime this is just `readonly number[]`, but TypeScript can
+ * distinguish it from regular arrays for query builder typing.
+ */
+type EmbeddingValue = readonly number[] & {
+    readonly [EMBEDDING_BRAND]: true;
+};
+/**
+ * Symbol key for storing embedding dimensions on the schema.
+ * This allows the schema introspector to detect embedding types
+ * and extract dimension information.
+ */
+declare const EMBEDDING_DIMENSIONS_KEY: "_embeddingDimensions";
+/**
+ * A Zod schema for vector embeddings with attached dimension metadata.
+ * Uses the branded EmbeddingValue type for type-level distinction.
+ */
+type EmbeddingSchema<D extends number = number> = z.ZodType<EmbeddingValue> & Readonly<{
+    [EMBEDDING_DIMENSIONS_KEY]: D;
+}>;
+/**
+ * Creates a Zod schema for vector embeddings.
+ *
+ * The dimension is validated at runtime and attached as metadata
+ * for the schema introspector and query compiler.
+ *
+ * @param dimensions - The number of dimensions (e.g., 384, 512, 768, 1536, 3072)
+ * @returns A Zod schema that validates embedding arrays
+ *
+ * @example
+ * ```typescript
+ * // OpenAI ada-002 embeddings
+ * const Document = defineNode("Document", {
+ *   schema: z.object({
+ *     title: z.string(),
+ *     embedding: embedding(1536),
+ *   }),
+ * });
+ *
+ * // Sentence transformers
+ * const Sentence = defineNode("Sentence", {
+ *   schema: z.object({
+ *     text: z.string(),
+ *     embedding: embedding(384), // all-MiniLM-L6-v2
+ *   }),
+ * });
+ *
+ * // Optional embeddings are supported
+ * const Article = defineNode("Article", {
+ *   schema: z.object({
+ *     content: z.string(),
+ *     embedding: embedding(1536).optional(),
+ *   }),
+ * });
+ * ```
+ */
+declare function embedding<D extends number>(dimensions: D): EmbeddingSchema<D>;
+/**
+ * Checks if a value is an embedding schema.
+ */
+declare function isEmbeddingSchema(value: unknown): value is EmbeddingSchema;
+/**
+ * Gets the dimensions from an embedding schema.
+ * Returns undefined if the schema is not an embedding schema.
+ */
+declare function getEmbeddingDimensions(schema: z.ZodType): number | undefined;
+
+/** Brand key for GraphDef */
+declare const GRAPH_DEF_BRAND: "__graphDef";
+/**
+ * An edge entry in the graph definition.
+ * Can be:
+ * - EdgeType directly (if it has from/to defined)
+ * - EdgeRegistration object (always works, can override/narrow defaults)
+ */
+type EdgeEntry = EdgeRegistration | EdgeTypeWithEndpoints;
+/**
+ * Normalized edge map type - all entries become EdgeRegistration.
+ */
+type NormalizedEdges<TEdges extends Record<string, EdgeEntry>> = {
+    [K in keyof TEdges]: TEdges[K] extends EdgeRegistration ? TEdges[K] : TEdges[K] extends EdgeTypeWithEndpoints ? EdgeRegistration<TEdges[K], TEdges[K]["from"][number], TEdges[K]["to"][number]> : never;
+};
+/**
+ * Configuration for defineGraph.
+ */
+type GraphDefConfig<TNodes extends Record<string, NodeRegistration>, TEdges extends Record<string, EdgeEntry>, TOntology extends readonly OntologyRelation[]> = Readonly<{
+    /** Unique identifier for this graph */
+    id: string;
+    /** Node registrations */
+    nodes: TNodes;
+    /** Edge registrations or EdgeTypes with built-in domain/range */
+    edges: TEdges;
+    /** Ontology relations */
+    ontology?: TOntology;
+    /** Graph-wide defaults */
+    defaults?: GraphDefaults;
+}>;
+/**
+ * A graph definition.
+ *
+ * This is a compile-time artifact that describes the structure of a graph.
+ * Use `createStore()` to create a runtime store from this definition.
+ */
+type GraphDef<TNodes extends Record<string, NodeRegistration> = Record<string, NodeRegistration>, TEdges extends Record<string, EdgeRegistration> = Record<string, EdgeRegistration>, TOntology extends readonly OntologyRelation[] = readonly OntologyRelation[]> = Readonly<{
+    [GRAPH_DEF_BRAND]: true;
+    id: string;
+    nodes: TNodes;
+    edges: TEdges;
+    ontology: TOntology;
+    defaults: Readonly<{
+        onNodeDelete: DeleteBehavior;
+        temporalMode: TemporalMode;
+    }>;
+}>;
+/**
+ * Extract node type names from a GraphDef.
+ */
+type NodeTypeNames<G extends GraphDef> = keyof G["nodes"] & string;
+/**
+ * Extract edge type names from a GraphDef.
+ */
+type EdgeTypeNames<G extends GraphDef> = keyof G["edges"] & string;
+/**
+ * Get a NodeType from a GraphDef by name.
+ */
+type GetNodeType<G extends GraphDef, K extends NodeTypeNames<G>> = G["nodes"][K]["type"];
+/**
+ * Get an EdgeType from a GraphDef by name.
+ */
+type GetEdgeType<G extends GraphDef, K extends EdgeTypeNames<G>> = G["edges"][K]["type"];
+/**
+ * Get all NodeTypes from a GraphDef.
+ */
+type AllNodeTypes<G extends GraphDef> = {
+    [K in NodeTypeNames<G>]: G["nodes"][K]["type"];
+}[NodeTypeNames<G>];
+/**
+ * Get all EdgeTypes from a GraphDef.
+ */
+type AllEdgeTypes<G extends GraphDef> = {
+    [K in EdgeTypeNames<G>]: G["edges"][K]["type"];
+}[EdgeTypeNames<G>];
+/**
+ * Creates a graph definition.
+ *
+ * @example
+ * ```typescript
+ * const graph = defineGraph({
+ *   id: "my_graph",
+ *   nodes: {
+ *     Person: { type: Person },
+ *     Company: { type: Company },
+ *   },
+ *   edges: {
+ *     // Traditional EdgeRegistration syntax
+ *     worksAt: {
+ *       type: worksAt,
+ *       from: [Person],
+ *       to: [Company],
+ *       cardinality: "many",
+ *     },
+ *     // Or use EdgeType directly if it has from/to defined
+ *     knows,  // EdgeType with built-in domain/range
+ *   },
+ *   ontology: [
+ *     subClassOf(Company, Organization),
+ *     disjointWith(Person, Organization),
+ *   ],
+ *   defaults: {
+ *     onNodeDelete: "restrict",
+ *     temporalMode: "current",
+ *   },
+ * });
+ * ```
+ */
+declare function defineGraph<TNodes extends Record<string, NodeRegistration<NodeType>>, TEdges extends Record<string, EdgeEntry>, TOntology extends readonly OntologyRelation[]>(config: GraphDefConfig<TNodes, TEdges, TOntology>): GraphDef<TNodes, NormalizedEdges<TEdges>, TOntology>;
+/**
+ * Checks if a value is a GraphDef.
+ */
+declare function isGraphDef(value: unknown): value is GraphDef;
+/**
+ * Gets all node type names from a GraphDef.
+ */
+declare function getNodeTypeNames<G extends GraphDef>(graph: G): readonly string[];
+/**
+ * Gets all edge type names from a GraphDef.
+ */
+declare function getEdgeTypeNames<G extends GraphDef>(graph: G): readonly string[];
+
+/**
+ * KindRegistry holds precomputed closures for ontological reasoning.
+ *
+ * Computed at store initialization and cached for fast query-time lookups.
+ */
+declare class KindRegistry {
+    readonly nodeKinds: ReadonlyMap<string, NodeType>;
+    readonly edgeKinds: ReadonlyMap<string, AnyEdgeType>;
+    readonly subClassAncestors: ReadonlyMap<string, ReadonlySet<string>>;
+    readonly subClassDescendants: ReadonlyMap<string, ReadonlySet<string>>;
+    readonly broaderClosure: ReadonlyMap<string, ReadonlySet<string>>;
+    readonly narrowerClosure: ReadonlyMap<string, ReadonlySet<string>>;
+    readonly equivalenceSets: ReadonlyMap<string, ReadonlySet<string>>;
+    readonly iriToKind: ReadonlyMap<string, string>;
+    readonly disjointPairs: ReadonlySet<string>;
+    readonly partOfClosure: ReadonlyMap<string, ReadonlySet<string>>;
+    readonly hasPartClosure: ReadonlyMap<string, ReadonlySet<string>>;
+    readonly edgeInverses: ReadonlyMap<string, string>;
+    readonly edgeImplicationsClosure: ReadonlyMap<string, ReadonlySet<string>>;
+    readonly edgeImplyingClosure: ReadonlyMap<string, ReadonlySet<string>>;
+    constructor(nodeKinds: ReadonlyMap<string, NodeType>, edgeKinds: ReadonlyMap<string, AnyEdgeType>, closures: {
+        subClassAncestors: ReadonlyMap<string, ReadonlySet<string>>;
+        subClassDescendants: ReadonlyMap<string, ReadonlySet<string>>;
+        broaderClosure: ReadonlyMap<string, ReadonlySet<string>>;
+        narrowerClosure: ReadonlyMap<string, ReadonlySet<string>>;
+        equivalenceSets: ReadonlyMap<string, ReadonlySet<string>>;
+        iriToKind: ReadonlyMap<string, string>;
+        disjointPairs: ReadonlySet<string>;
+        partOfClosure: ReadonlyMap<string, ReadonlySet<string>>;
+        hasPartClosure: ReadonlyMap<string, ReadonlySet<string>>;
+        edgeInverses: ReadonlyMap<string, string>;
+        edgeImplicationsClosure: ReadonlyMap<string, ReadonlySet<string>>;
+        edgeImplyingClosure: ReadonlyMap<string, ReadonlySet<string>>;
+    });
+    /**
+     * Checks if child is a subclass of parent (directly or transitively).
+     */
+    isSubClassOf(child: string, parent: string): boolean;
+    /**
+     * Expands a kind to include all its subclasses.
+     * Returns [kind, ...subclasses].
+     */
+    expandSubClasses(kind: string): readonly string[];
+    /**
+     * Gets all ancestors of a kind (via subClassOf).
+     */
+    getAncestors(kind: string): ReadonlySet<string>;
+    /**
+     * Gets all descendants of a kind (via subClassOf).
+     */
+    getDescendants(kind: string): ReadonlySet<string>;
+    /**
+     * Checks if narrowerConcept is narrower than broaderConcept.
+     */
+    isNarrowerThan(narrowerConcept: string, broaderConcept: string): boolean;
+    /**
+     * Checks if broaderConcept is broader than narrowerConcept.
+     */
+    isBroaderThan(broaderConcept: string, narrowerConcept: string): boolean;
+    /**
+     * Expands to include all narrower concepts.
+     */
+    expandNarrower(kind: string): readonly string[];
+    /**
+     * Expands to include all broader concepts.
+     */
+    expandBroader(kind: string): readonly string[];
+    /**
+     * Checks if two kinds are equivalent.
+     */
+    areEquivalent(a: string, b: string): boolean;
+    /**
+     * Gets all equivalents of a kind (including external IRIs).
+     */
+    getEquivalents(kind: string): readonly string[];
+    /**
+     * Resolves an external IRI to an internal kind name.
+     */
+    resolveIri(iri: string): string | undefined;
+    /**
+     * Checks if two kinds are disjoint.
+     */
+    areDisjoint(a: string, b: string): boolean;
+    /**
+     * Gets all kinds that are disjoint with the given kind.
+     */
+    getDisjointKinds(kind: string): readonly string[];
+    /**
+     * Checks if part is part of whole (directly or transitively).
+     */
+    isPartOf(part: string, whole: string): boolean;
+    /**
+     * Gets all wholes that contain this part.
+     */
+    getWholes(part: string): readonly string[];
+    /**
+     * Gets all parts of this whole.
+     */
+    getParts(whole: string): readonly string[];
+    /**
+     * Gets the inverse edge kind for a given edge kind.
+     * If edgeA inverseOf edgeB, then getInverseEdge("edgeA") returns "edgeB".
+     */
+    getInverseEdge(edgeKind: string): string | undefined;
+    /**
+     * Gets all edges implied by a given edge (transitively).
+     * If A implies B and B implies C, then getImpliedEdges("A") returns ["B", "C"].
+     */
+    getImpliedEdges(edgeKind: string): readonly string[];
+    /**
+     * Gets all edges that imply a given edge (transitively).
+     * If A implies B and B implies C, then getImplyingEdges("C") returns ["A", "B"].
+     * Used for query-time expansion: when querying for C, also include A and B edges.
+     */
+    getImplyingEdges(edgeKind: string): readonly string[];
+    /**
+     * Expands an edge kind to include all edges that imply it.
+     * Returns [edgeKind, ...implyingEdges].
+     */
+    expandImplyingEdges(edgeKind: string): readonly string[];
+    /**
+     * Checks if a concrete kind is assignable to a target kind.
+     * Uses subsumption: Company is assignable to Organization if Company subClassOf Organization.
+     */
+    isAssignableTo(concreteKind: string, targetKind: string): boolean;
+    /**
+     * Validates that a kind exists in the registry.
+     */
+    hasNodeType(name: string): boolean;
+    /**
+     * Validates that an edge kind exists in the registry.
+     */
+    hasEdgeType(name: string): boolean;
+    /**
+     * Gets a node kind by name.
+     */
+    getNodeType(name: string): NodeType | undefined;
+    /**
+     * Gets an edge kind by name.
+     */
+    getEdgeType(name: string): AnyEdgeType | undefined;
+}
+
+/**
+ * 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.
+ */
+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;
+}>;
+/**
+ * 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;
+}>;
+
+/**
+ * Store types for TypeGraph operations.
+ */
+
+/**
+ * Metadata for a node instance.
+ */
+type NodeMeta = Readonly<{
+    version: number;
+    validFrom: string | undefined;
+    validTo: string | undefined;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: string | undefined;
+}>;
+/**
+ * A node instance in the graph.
+ *
+ * Properties from the schema are spread at the top level for ergonomic access:
+ * - `node.name` instead of `node.props.name`
+ * - System metadata is under `node.meta.*`
+ */
+type Node<N extends NodeType = NodeType> = Readonly<{
+    kind: N["name"];
+    id: NodeId<N>;
+    meta: NodeMeta;
+}> & Readonly<z.infer<N["schema"]>>;
+/**
+ * Input for creating a node.
+ */
+type CreateNodeInput<N extends NodeType = NodeType> = Readonly<{
+    kind: N["name"];
+    id?: string;
+    props: z.infer<N["schema"]>;
+    validFrom?: string;
+    validTo?: string;
+}>;
+/**
+ * Input for updating a node.
+ */
+type UpdateNodeInput<N extends NodeType = NodeType> = Readonly<{
+    kind: N["name"];
+    id: NodeId<N>;
+    props: Partial<z.infer<N["schema"]>>;
+    validTo?: string;
+}>;
+/**
+ * Metadata for an edge instance.
+ */
+type EdgeMeta = Readonly<{
+    validFrom: string | undefined;
+    validTo: string | undefined;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: string | undefined;
+}>;
+/**
+ * An edge instance in the graph.
+ *
+ * Properties from the schema are spread at the top level for ergonomic access:
+ * - `edge.role` instead of `edge.props.role`
+ * - System metadata is under `edge.meta.*`
+ */
+type Edge<E extends AnyEdgeType = EdgeType> = Readonly<{
+    id: string;
+    kind: E["name"];
+    fromKind: string;
+    fromId: string;
+    toKind: string;
+    toId: string;
+    meta: EdgeMeta;
+}> & Readonly<z.infer<E["schema"]>>;
+/**
+ * Input for creating an edge.
+ */
+type CreateEdgeInput<E extends AnyEdgeType = EdgeType> = Readonly<{
+    kind: E["name"];
+    id?: string;
+    fromKind: string;
+    fromId: string;
+    toKind: string;
+    toId: string;
+    props: z.infer<E["schema"]>;
+    validFrom?: string;
+    validTo?: string;
+}>;
+/**
+ * Input for updating an edge.
+ */
+type UpdateEdgeInput<E extends AnyEdgeType = EdgeType> = Readonly<{
+    id: string;
+    props: Partial<z.infer<E["schema"]>>;
+    validTo?: string;
+}>;
+/**
+ * Options for node and edge queries.
+ */
+type QueryOptions = Readonly<{
+    /** Temporal mode for the query */
+    temporalMode?: TemporalMode;
+    /** Specific timestamp for asOf queries */
+    asOf?: string;
+}>;
+/**
+ * Context passed to observability hooks.
+ */
+type HookContext = Readonly<{
+    /** Unique ID for this operation */
+    operationId: string;
+    /** Graph ID */
+    graphId: string;
+    /** Timestamp when operation started */
+    startedAt: Date;
+}>;
+/**
+ * Query hook context with SQL information.
+ */
+type QueryHookContext = HookContext & Readonly<{
+    /** The SQL query being executed */
+    sql: string;
+    /** Query parameters */
+    params: readonly unknown[];
+}>;
+/**
+ * Operation hook context for CRUD operations.
+ */
+type OperationHookContext = HookContext & Readonly<{
+    /** Operation type */
+    operation: "create" | "update" | "delete";
+    /** Entity type */
+    entity: "node" | "edge";
+    /** Kind of node or edge */
+    kind: string;
+    /** Entity ID */
+    id: string;
+}>;
+/**
+ * Observability hooks for monitoring store operations.
+ *
+ * @example
+ * ```typescript
+ * const hooks: StoreHooks = {
+ *   onQueryStart: (ctx) => {
+ *     console.log(`[${ctx.operationId}] Query: ${ctx.sql}`);
+ *   },
+ *   onQueryEnd: (ctx, result) => {
+ *     const duration = Date.now() - ctx.startedAt.getTime();
+ *     console.log(`[${ctx.operationId}] Completed in ${duration}ms`);
+ *   },
+ *   onError: (ctx, error) => {
+ *     console.error(`[${ctx.operationId}] Error:`, error);
+ *   },
+ * };
+ *
+ * const store = createStore(graph, backend, { hooks });
+ * ```
+ */
+type StoreHooks = Readonly<{
+    /** Called before a query is executed */
+    onQueryStart?: (ctx: QueryHookContext) => void;
+    /** Called after a query completes successfully */
+    onQueryEnd?: (ctx: QueryHookContext, result: Readonly<{
+        rowCount: number;
+        durationMs: number;
+    }>) => void;
+    /** Called before a CRUD operation starts */
+    onOperationStart?: (ctx: OperationHookContext) => void;
+    /** Called after a CRUD operation completes */
+    onOperationEnd?: (ctx: OperationHookContext, result: Readonly<{
+        durationMs: number;
+    }>) => void;
+    /** Called when an error occurs */
+    onError?: (ctx: HookContext, error: Error) => void;
+}>;
+/**
+ * Options for creating a store.
+ */
+type StoreOptions = Readonly<{
+    /** Observability hooks for monitoring */
+    hooks?: StoreHooks;
+    /** SQL schema configuration for custom table names */
+    schema?: SqlSchema;
+}>;
+/**
+ * Configuration for creating a store.
+ */
+type StoreConfig<G extends GraphDef> = Readonly<{
+    /** The graph definition */
+    graph: G;
+    /** Database connection string or path */
+    connection?: string;
+    /** Auto-run migrations */
+    autoMigrate?: boolean;
+}>;
+/**
+ * A collection of nodes of a specific type.
+ *
+ * Provides ergonomic CRUD operations for a single node type.
+ */
+type NodeCollection<N extends NodeType> = Readonly<{
+    /** Create a new node */
+    create: (props: z.input<N["schema"]>, options?: Readonly<{
+        id?: string;
+        validFrom?: string;
+        validTo?: string;
+    }>) => Promise<Node<N>>;
+    /** Get a node by ID */
+    getById: (id: NodeId<N>, options?: QueryOptions) => Promise<Node<N> | undefined>;
+    /** Update a node */
+    update: (id: NodeId<N>, props: Partial<z.input<N["schema"]>>, options?: Readonly<{
+        validTo?: string;
+    }>) => Promise<Node<N>>;
+    /** Delete a node (soft delete - sets deletedAt timestamp) */
+    delete: (id: NodeId<N>) => Promise<void>;
+    /**
+     * Permanently delete a node from the database.
+     *
+     * Unlike `delete()` which performs a soft delete, this permanently
+     * removes the node and its associated data (uniqueness entries, embeddings).
+     *
+     * **Warning:** This operation is irreversible and should be used carefully.
+     * Consider using soft delete (`delete()`) for most use cases.
+     *
+     * @throws Error if edges are still connected to this node (delete edges first)
+     */
+    hardDelete: (id: NodeId<N>) => Promise<void>;
+    /**
+     * Find nodes matching criteria.
+     *
+     * For simple queries. Use store.query() for complex traversals.
+     */
+    find: (options?: Readonly<{
+        limit?: number;
+        offset?: number;
+    }>) => Promise<Node<N>[]>;
+    /** Count nodes matching criteria */
+    count: () => Promise<number>;
+    /**
+     * Create or update a node.
+     *
+     * If a node with the given ID exists, updates it with the provided props.
+     * Otherwise, creates a new node with that ID.
+     */
+    upsert: (id: string, props: z.input<N["schema"]>, options?: Readonly<{
+        validFrom?: string;
+        validTo?: string;
+    }>) => Promise<Node<N>>;
+    /**
+     * Create multiple nodes in a batch.
+     *
+     * More efficient than calling create() multiple times.
+     */
+    bulkCreate: (items: readonly Readonly<{
+        props: z.input<N["schema"]>;
+        id?: string;
+        validFrom?: string;
+        validTo?: string;
+    }>[]) => Promise<Node<N>[]>;
+    /**
+     * Create or update multiple nodes in a batch.
+     *
+     * For each item, if a node with the given ID exists, updates it.
+     * Otherwise, creates a new node with that ID.
+     */
+    bulkUpsert: (items: readonly Readonly<{
+        id: string;
+        props: z.input<N["schema"]>;
+        validFrom?: string;
+        validTo?: string;
+    }>[]) => Promise<Node<N>[]>;
+    /**
+     * Delete multiple nodes by ID.
+     *
+     * Silently ignores IDs that don't exist.
+     */
+    bulkDelete: (ids: readonly NodeId<N>[]) => Promise<void>;
+}>;
+/**
+ * Reference to a node endpoint (kind and id).
+ *
+ * Can be either an explicit `{ kind, id }` object or a Node instance.
+ */
+type NodeRef = Readonly<{
+    kind: string;
+    id: string;
+}>;
+/**
+ * Type-safe reference to a node of a specific kind.
+ *
+ * Accepts either:
+ * - A Node instance of the correct kind
+ * - An explicit { kind, id } object with the correct kind name
+ *
+ * This provides compile-time checking that edge endpoints match the
+ * allowed node kinds defined in the edge registration.
+ */
+type TypedNodeRef<N extends NodeType> = Node<N> | Readonly<{
+    kind: N["name"];
+    id: string;
+}>;
+/**
+ * Options for creating an edge.
+ */
+type EdgeCreateOptions = Readonly<{
+    id?: string;
+    validFrom?: string;
+    validTo?: string;
+}>;
+/**
+ * Arguments for edge creation, with props optional when schema allows empty object.
+ *
+ * Uses `{}` to check if an empty object literal satisfies the schema input type.
+ */
+type EdgeCreateArguments<E extends AnyEdgeType> = {} extends z.input<E["schema"]> ? [
+    props?: z.input<E["schema"]>,
+    options?: EdgeCreateOptions
+] : [props: z.input<E["schema"]>, options?: EdgeCreateOptions];
+/**
+ * A collection of edges of a specific type.
+ *
+ * Provides ergonomic CRUD operations for a single edge type.
+ * The From and To type parameters enforce that edge endpoints
+ * match the allowed node types at compile time.
+ *
+ * @example
+ * ```typescript
+ * // Create an edge - pass Node objects directly
+ * const edge = await store.edges.worksAt.create(alice, acme, { role: "Engineer" });
+ *
+ * // TypeScript error: Company is not a valid 'from' type for worksAt
+ * // store.edges.worksAt.create(acme, alice, { role: "Engineer" });
+ *
+ * // For edges with empty schemas, props is optional
+ * await store.edges.wrote.create(author, book);
+ *
+ * // Find edges from a node
+ * const edges = await store.edges.worksAt.findFrom(alice);
+ * ```
+ */
+type EdgeCollection<E extends AnyEdgeType, From extends NodeType = NodeType, To extends NodeType = NodeType> = Readonly<{
+    /**
+     * Create a new edge.
+     *
+     * @param from - Source node (must be one of the allowed 'from' types)
+     * @param to - Target node (must be one of the allowed 'to' types)
+     * @param args - Edge properties (optional if schema is empty) and creation options
+     */
+    create: (from: TypedNodeRef<From>, to: TypedNodeRef<To>, ...args: EdgeCreateArguments<E>) => Promise<Edge<E>>;
+    /** Get an edge by ID */
+    getById: (id: string, options?: QueryOptions) => Promise<Edge<E> | undefined>;
+    /** Update an edge's properties */
+    update: (id: string, props: Partial<z.input<E["schema"]>>, options?: Readonly<{
+        validTo?: string;
+    }>) => Promise<Edge<E>>;
+    /** Find edges from a specific node */
+    findFrom: (from: TypedNodeRef<From>) => Promise<Edge<E>[]>;
+    /** Find edges to a specific node */
+    findTo: (to: TypedNodeRef<To>) => Promise<Edge<E>[]>;
+    /** Delete an edge (soft delete - sets deletedAt timestamp) */
+    delete: (id: string) => Promise<void>;
+    /**
+     * Permanently delete an edge from the database.
+     *
+     * Unlike `delete()` which performs a soft delete, this permanently
+     * removes the edge record.
+     *
+     * **Warning:** This operation is irreversible and should be used carefully.
+     * Consider using soft delete (`delete()`) for most use cases.
+     */
+    hardDelete: (id: string) => Promise<void>;
+    /** Find edges matching criteria */
+    find: (options?: Readonly<{
+        from?: TypedNodeRef<From>;
+        to?: TypedNodeRef<To>;
+        limit?: number;
+        offset?: number;
+    }>) => Promise<Edge<E>[]>;
+    /** Count edges matching criteria */
+    count: (options?: Readonly<{
+        from?: TypedNodeRef<From>;
+        to?: TypedNodeRef<To>;
+    }>) => Promise<number>;
+    /**
+     * Create multiple edges in a batch.
+     *
+     * More efficient than calling create() multiple times.
+     */
+    bulkCreate: (items: readonly Readonly<{
+        from: TypedNodeRef<From>;
+        to: TypedNodeRef<To>;
+        props?: z.input<E["schema"]>;
+        id?: string;
+        validFrom?: string;
+        validTo?: string;
+    }>[]) => Promise<Edge<E>[]>;
+    /**
+     * Delete multiple edges by ID.
+     *
+     * Silently ignores IDs that don't exist.
+     */
+    bulkDelete: (ids: readonly string[]) => Promise<void>;
+}>;
+/**
+ * Extract the union of 'from' node types from an EdgeRegistration.
+ */
+type EdgeFromTypes<R extends EdgeRegistration> = R["from"] extends readonly (infer N)[] ? N : never;
+/**
+ * Extract the union of 'to' node types from an EdgeRegistration.
+ */
+type EdgeToTypes<R extends EdgeRegistration> = R["to"] extends readonly (infer N)[] ? N : never;
+/**
+ * Create a type-safe EdgeCollection from an EdgeRegistration.
+ * Extracts the edge type and from/to node types automatically.
+ */
+type TypedEdgeCollection<R extends EdgeRegistration> = EdgeCollection<R["type"], EdgeFromTypes<R> extends NodeType ? EdgeFromTypes<R> : NodeType, EdgeToTypes<R> extends NodeType ? EdgeToTypes<R> : NodeType>;
+/**
+ * A typed transaction context with collection API.
+ *
+ * Provides the same `tx.nodes.*` and `tx.edges.*` API as the Store,
+ * but operations are executed within the transaction scope.
+ *
+ * @example
+ * ```typescript
+ * await store.transaction(async (tx) => {
+ *   const person = await tx.nodes.Person.create({ name: "Alice" });
+ *   const company = await tx.nodes.Company.create({ name: "Acme" });
+ *   // Pass nodes directly - their kind and id properties are used
+ *   await tx.edges.worksAt.create(person, company, { role: "Engineer" });
+ * });
+ * ```
+ */
+type TransactionContext<G extends GraphDef> = Readonly<{
+    /** Node collections for the transaction */
+    nodes: {
+        [K in keyof G["nodes"] & string]-?: NodeCollection<G["nodes"][K]["type"]>;
+    };
+    /** Edge collections for the transaction */
+    edges: {
+        [K in keyof G["edges"] & string]-?: TypedEdgeCollection<G["edges"][K]>;
+    };
+}>;
+
+type FieldTypeInfo = Readonly<{
+    valueType: ValueType;
+    elementType?: ValueType | undefined;
+    elementTypeInfo?: FieldTypeInfo | undefined;
+    shape?: Readonly<Record<string, FieldTypeInfo>> | undefined;
+    recordValueType?: FieldTypeInfo | undefined;
+    /** For embedding types: the number of dimensions */
+    dimensions?: number | undefined;
+}>;
+type SchemaIntrospector = Readonly<{
+    getFieldTypeInfo: (kindName: string, fieldName: string) => FieldTypeInfo | undefined;
+    getSharedFieldTypeInfo: (kindNames: readonly string[], fieldName: string) => FieldTypeInfo | undefined;
+    getEdgeFieldTypeInfo: (edgeKindName: string, fieldName: string) => FieldTypeInfo | undefined;
+    getSharedEdgeFieldTypeInfo: (edgeKindNames: readonly string[], fieldName: string) => FieldTypeInfo | undefined;
+}>;
+
+/**
+ * Predicate builders for TypeGraph queries.
+ *
+ * Provides a fluent API for building type-safe predicates.
+ */
+
+/**
+ * A chainable predicate that can be combined with AND/OR.
+ */
+type Predicate = Readonly<{
+    __expr: PredicateExpression;
+    and: (other: Predicate) => Predicate;
+    or: (other: Predicate) => Predicate;
+    not: () => Predicate;
+}>;
+/**
+ * Options for the similarTo method.
+ */
+type SimilarToOptions = Readonly<{
+    /** Similarity metric to use. Default: "cosine" */
+    metric?: VectorMetricType;
+    /**
+     * Minimum similarity score to include results.
+     * For cosine: 0-1 where 1 is identical.
+     * For L2: maximum distance to include.
+     * For inner_product: minimum inner product value.
+     */
+    minScore?: number;
+}>;
+/**
+ * Creates a field reference.
+ */
+type FieldRefOptions = Readonly<{
+    jsonPointer?: JsonPointer | undefined;
+    valueType?: ValueType | undefined;
+    elementType?: ValueType | undefined;
+}>;
+declare function fieldRef(alias: string, path: readonly string[], options?: FieldRefOptions): FieldRef;
+/**
+ * Creates an EXISTS subquery predicate.
+ * Returns true if the subquery returns at least one row.
+ *
+ * @param subquery - The subquery AST to check for existence
+ *
+ * @example
+ * ```typescript
+ * // Find persons who have at least one order
+ * query
+ *   .from("Person", "p")
+ *   .whereNode("p", () =>
+ *     exists(
+ *       query.from("Order", "o")
+ *         .whereNode("o", (o) => o.customerId.eq(field("p.id")))
+ *         .select((ctx) => ({ id: ctx.o.id }))
+ *         .toAst()
+ *     )
+ *   )
+ * ```
+ */
+declare function exists(subquery: QueryAst): Predicate;
+/**
+ * Creates a NOT EXISTS subquery predicate.
+ * Returns true if the subquery returns no rows.
+ *
+ * @param subquery - The subquery AST to check for non-existence
+ */
+declare function notExists(subquery: QueryAst): Predicate;
+/**
+ * Creates an IN subquery predicate.
+ * Returns true if the field value is in the subquery results.
+ *
+ * @param field - The field to check
+ * @param subquery - The subquery AST that returns a single column
+ *
+ * @example
+ * ```typescript
+ * // Find persons whose ID is in the VIP list
+ * query
+ *   .from("Person", "p")
+ *   .where(() =>
+ *     inSubquery(
+ *       fieldRef("p", ["id"]),
+ *       query.from("VIPMember", "v")
+ *         .select({ id: field("v.personId") })
+ *         .toAst()
+ *     )
+ *   )
+ * ```
+ */
+declare function inSubquery(field: FieldRef, subquery: QueryAst): Predicate;
+/**
+ * Creates a NOT IN subquery predicate.
+ * Returns true if the field value is not in the subquery results.
+ *
+ * @param field - The field to check
+ * @param subquery - The subquery AST that returns a single column
+ */
+declare function notInSubquery(field: FieldRef, subquery: QueryAst): Predicate;
+
+/**
+ * Shared type definitions for the query builder.
+ *
+ * Contains type definitions used across QueryBuilder, TraversalBuilder,
+ * and ExecutableQuery classes.
+ */
+
+/**
+ * Extracts the names of valid target node kinds for an edge traversal.
+ *
+ * For "out" direction: returns the names of node kinds in the edge's "to" array.
+ * For "in" direction: returns the names of node kinds in the edge's "from" array.
+ *
+ * @example
+ * // Given: worksAt: { from: [Person], to: [Company, Organization] }
+ * // ValidEdgeTargets<G, "worksAt", "out"> = "Company" | "Organization"
+ * // ValidEdgeTargets<G, "worksAt", "in"> = "Person"
+ */
+type ValidEdgeTargets<G extends GraphDef, EK extends keyof G["edges"] & string, Dir extends TraversalDirection> = G["edges"][EK] extends EdgeRegistration ? Dir extends "out" ? G["edges"][EK]["to"][number]["name"] : G["edges"][EK]["from"][number]["name"] : never;
+/**
+ * A node alias with its associated kind.
+ */
+type NodeAlias<K extends NodeType = NodeType, Optional extends boolean = false> = Readonly<{
+    kind: K;
+    alias: string;
+    optional: Optional;
+}>;
+/**
+ * A map of alias names to their node aliases.
+ */
+type AliasMap = Readonly<Record<string, NodeAlias<NodeType, boolean>>>;
+/**
+ * An edge alias with its associated kind and optional flag.
+ */
+type EdgeAlias<E extends AnyEdgeType = EdgeType, Optional extends boolean = false> = Readonly<{
+    kind: E;
+    alias: string;
+    optional: Optional;
+}>;
+/**
+ * A map of alias names to their edge aliases.
+ */
+type EdgeAliasMap = Readonly<Record<string, EdgeAlias<EdgeType, boolean>>>;
+/**
+ * Type utility for compile-time alias collision detection.
+ *
+ * When A already exists in Aliases, this resolves to an error message type
+ * that will cause a type error with a descriptive message.
+ */
+type UniqueAlias<A extends string, Aliases extends AliasMap> = A extends keyof Aliases ? `Error: Alias '${A}' is already in use` : A;
+/**
+ * Creates typed field accessors for a node kind's properties.
+ */
+type PropsAccessor<N extends NodeType> = Readonly<{
+    [K in keyof z.infer<N["schema"]>]-?: FieldAccessor<z.infer<N["schema"]>[K]>;
+}>;
+/**
+ * A field accessor with type-appropriate predicate methods.
+ * Uses NonNullable to handle optional fields correctly.
+ */
+type FieldAccessor<T> = FieldAccessorForType<NonNullable<T>>;
+type FieldAccessorForType<T> = [
+    T
+] extends [EmbeddingValue] ? EmbeddingFieldAccessor : [T] extends [string] ? StringFieldAccessor : [T] extends [number] ? NumberFieldAccessor : [T] extends [boolean] ? BooleanFieldAccessor : [T] extends [Date] ? DateFieldAccessor : [T] extends [readonly (infer U)[]] ? ArrayFieldAccessor<U> : [T] extends [Record<string, unknown>] ? ObjectFieldAccessor<T> : BaseFieldAccessor;
+type BaseFieldAccessor = Readonly<{
+    eq: (value: unknown) => Predicate;
+    neq: (value: unknown) => Predicate;
+    isNull: () => Predicate;
+    isNotNull: () => Predicate;
+    in: (values: readonly unknown[]) => Predicate;
+    notIn: (values: readonly unknown[]) => Predicate;
+}>;
+type StringFieldAccessor = BaseFieldAccessor & Readonly<{
+    contains: (pattern: string) => Predicate;
+    startsWith: (pattern: string) => Predicate;
+    endsWith: (pattern: string) => Predicate;
+    like: (pattern: string) => Predicate;
+    ilike: (pattern: string) => Predicate;
+}>;
+type NumberFieldAccessor = BaseFieldAccessor & Readonly<{
+    gt: (value: number) => Predicate;
+    gte: (value: number) => Predicate;
+    lt: (value: number) => Predicate;
+    lte: (value: number) => Predicate;
+    between: (lower: number, upper: number) => Predicate;
+}>;
+type BooleanFieldAccessor = BaseFieldAccessor;
+type DateFieldAccessor = BaseFieldAccessor & Readonly<{
+    gt: (value: Date | string) => Predicate;
+    gte: (value: Date | string) => Predicate;
+    lt: (value: Date | string) => Predicate;
+    lte: (value: Date | string) => Predicate;
+    between: (lower: Date | string, upper: Date | string) => Predicate;
+}>;
+type ArrayFieldAccessor<U> = BaseFieldAccessor & Readonly<{
+    contains: (value: U) => Predicate;
+    containsAny: (values: readonly U[]) => Predicate;
+    containsAll: (values: readonly U[]) => Predicate;
+    length: NumberFieldAccessor;
+    isEmpty: () => Predicate;
+    isNotEmpty: () => Predicate;
+    lengthEq: (length: number) => Predicate;
+    lengthGt: (length: number) => Predicate;
+    lengthGte: (length: number) => Predicate;
+    lengthLt: (length: number) => Predicate;
+    lengthLte: (length: number) => Predicate;
+}>;
+type EmbeddingFieldAccessor = BaseFieldAccessor & Readonly<{
+    /**
+     * Finds the k most similar items using vector similarity.
+     *
+     * @param queryEmbedding - The query vector to compare against
+     * @param k - Maximum number of results to return
+     * @param options - Optional metric and minimum score filter
+     */
+    similarTo: (queryEmbedding: readonly number[], k: number, options?: SimilarToOptions) => Predicate;
+}>;
+type ObjectFieldAccessor<T> = BaseFieldAccessor & Readonly<{
+    get: <K extends keyof T & string>(key: K) => T[K] extends Record<string, unknown> ? ObjectFieldAccessor<T[K]> : FieldAccessor<T[K]>;
+    hasKey: (key: string) => Predicate;
+    hasPath: <P extends JsonPointerInput<T>>(pointer: P) => Predicate;
+    pathEquals: <P extends JsonPointerInput<T>>(pointer: P, value: string | number | boolean | Date) => Predicate;
+    pathContains: <P extends JsonPointerInput<T>>(pointer: P, value: string | number | boolean | Date) => Predicate;
+    pathIsNull: <P extends JsonPointerInput<T>>(pointer: P) => Predicate;
+    pathIsNotNull: <P extends JsonPointerInput<T>>(pointer: P) => Predicate;
+}>;
+/**
+ * Node accessor for predicate building.
+ *
+ * Properties are available at the top level for ergonomic access:
+ * - `n.name` instead of `n.props.name`
+ * - System fields: `n.id`, `n.kind`
+ */
+type NodeAccessor<N extends NodeType> = Readonly<{
+    id: StringFieldAccessor;
+    kind: StringFieldAccessor;
+}> & PropsAccessor<N>;
+/**
+ * Creates typed field accessors for an edge kind's properties.
+ */
+type EdgePropsAccessor<E extends AnyEdgeType> = Readonly<{
+    [K in keyof z.infer<E["schema"]>]-?: FieldAccessor<z.infer<E["schema"]>[K]>;
+}>;
+/**
+ * Edge accessor for predicate building.
+ *
+ * Properties are available at the top level for ergonomic access:
+ * - `e.role` instead of `e.props.role`
+ * - System fields: `e.id`, `e.kind`, `e.fromId`, `e.toId`
+ */
+type EdgeAccessor<E extends AnyEdgeType> = Readonly<{
+    id: StringFieldAccessor;
+    kind: StringFieldAccessor;
+    fromId: StringFieldAccessor;
+    toId: StringFieldAccessor;
+}> & EdgePropsAccessor<E>;
+/**
+ * Metadata for a selectable node result.
+ */
+type SelectableNodeMeta = Readonly<{
+    version: number;
+    validFrom: string | undefined;
+    validTo: string | undefined;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: string | undefined;
+}>;
+/**
+ * A selectable node result.
+ *
+ * Properties from the schema are spread at the top level for ergonomic access:
+ * - `node.name` instead of `node.props.name`
+ * - System metadata is under `node.meta.*`
+ */
+type SelectableNode<N extends NodeType> = Readonly<{
+    id: string;
+    kind: N["name"];
+    meta: SelectableNodeMeta;
+}> & Readonly<z.infer<N["schema"]>>;
+/**
+ * Metadata for a selectable edge result.
+ */
+type SelectableEdgeMeta = Readonly<{
+    validFrom: string | undefined;
+    validTo: string | undefined;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: string | undefined;
+}>;
+/**
+ * A selectable edge result.
+ *
+ * Properties from the schema are spread at the top level for ergonomic access:
+ * - `edge.role` instead of `edge.props.role`
+ * - System metadata is under `edge.meta.*`
+ */
+type SelectableEdge<E extends AnyEdgeType = EdgeType> = Readonly<{
+    id: string;
+    kind: E["name"];
+    fromId: string;
+    toId: string;
+    meta: SelectableEdgeMeta;
+}> & Readonly<z.infer<E["schema"]>>;
+/**
+ * Selection context passed to select callback.
+ *
+ * Includes both node aliases and edge aliases. Edge aliases from optional
+ * traversals are nullable.
+ */
+type SelectContext<Aliases extends AliasMap, EdgeAliases extends EdgeAliasMap = Record<string, never>> = Readonly<{
+    [A in keyof Aliases]: Aliases[A]["optional"] extends true ? SelectableNode<Aliases[A]["kind"]> | undefined : SelectableNode<Aliases[A]["kind"]>;
+}> & Readonly<{
+    [EA in keyof EdgeAliases]: EdgeAliases[EA]["optional"] extends true ? SelectableEdge<EdgeAliases[EA]["kind"]> | undefined : SelectableEdge<EdgeAliases[EA]["kind"]>;
+}>;
+/**
+ * Result of a paginated query.
+ */
+type PaginatedResult<R> = Readonly<{
+    /** The data items for this page */
+    data: readonly R[];
+    /** Cursor to fetch the next page (undefined if no more pages) */
+    nextCursor: string | undefined;
+    /** Cursor to fetch the previous page (undefined if on first page) */
+    prevCursor: string | undefined;
+    /** Whether there are more items after this page */
+    hasNextPage: boolean;
+    /** Whether there are items before this page */
+    hasPrevPage: boolean;
+}>;
+/**
+ * Options for cursor-based pagination.
+ *
+ * Use `first`/`after` for forward pagination, `last`/`before` for backward.
+ */
+type PaginateOptions = Readonly<{
+    /** Number of items to fetch (forward pagination) */
+    first?: number;
+    /** Cursor to start after (forward pagination) */
+    after?: string;
+    /** Number of items to fetch (backward pagination) */
+    last?: number;
+    /** Cursor to start before (backward pagination) */
+    before?: string;
+}>;
+/**
+ * Options for streaming results.
+ */
+type StreamOptions = Readonly<{
+    /** Number of items to fetch per batch (default: 1000) */
+    batchSize?: number;
+}>;
+/**
+ * Configuration for the query builder.
+ */
+type QueryBuilderConfig = Readonly<{
+    graphId: string;
+    registry: KindRegistry;
+    schemaIntrospector: SchemaIntrospector;
+    backend?: GraphBackend;
+    dialect?: SqlDialect;
+    /** SQL schema configuration for custom table names. */
+    schema?: SqlSchema;
+}>;
+/**
+ * Internal state of the query builder.
+ */
+type QueryBuilderState = Readonly<{
+    startAlias: string;
+    startKinds: readonly string[];
+    /** The current alias (last traversal target, or startAlias if no traversals) */
+    currentAlias: string;
+    includeSubClasses: boolean;
+    traversals: readonly Traversal[];
+    predicates: readonly NodePredicate[];
+    projection: readonly ProjectedField[];
+    orderBy: readonly OrderSpec[];
+    limit: number | undefined;
+    offset: number | undefined;
+    temporalMode: TemporalMode;
+    asOf: string | undefined;
+    groupBy: GroupBySpec | undefined;
+    having: PredicateExpression | undefined;
+}>;
+/**
+ * Options for creating a query builder.
+ */
+type CreateQueryBuilderOptions = Readonly<{
+    /** Backend for query execution */
+    backend?: GraphBackend;
+    /** SQL dialect for compilation */
+    dialect?: SqlDialect;
+    /** SQL schema configuration for custom table names */
+    schema?: SqlSchema;
+}>;
+
+/**
+ * ExecutableAggregateQuery - A query with aggregate functions that can be executed.
+ */
+
+/**
+ * Result type for aggregate queries.
+ * Maps field refs to their value types and aggregates to numbers.
+ */
+type AggregateResult<R extends Record<string, FieldRef | AggregateExpr>> = {
+    [K in keyof R]: R[K] extends AggregateExpr ? number : R[K] extends FieldRef ? unknown : never;
+};
+/**
+ * An aggregate query that can be executed.
+ */
+declare class ExecutableAggregateQuery<G extends GraphDef, Aliases extends AliasMap, R extends Record<string, FieldRef | AggregateExpr>> {
+    #private;
+    constructor(config: QueryBuilderConfig, state: QueryBuilderState, fields: R);
+    /**
+     * Builds the query AST.
+     */
+    toAst(): QueryAst;
+    /**
+     * Limits the number of results.
+     */
+    limit(n: number): ExecutableAggregateQuery<G, Aliases, R>;
+    /**
+     * Offsets the results.
+     */
+    offset(n: number): ExecutableAggregateQuery<G, Aliases, R>;
+    /**
+     * Compiles the query to a Drizzle SQL object.
+     */
+    compile(): SQL;
+    /**
+     * Executes the query and returns typed results.
+     *
+     * @throws Error if no backend is configured
+     */
+    execute(): Promise<readonly AggregateResult<R>[]>;
+}
+
+/**
+ * UnionableQuery - A query formed by combining multiple queries with set operations.
+ */
+
+interface ExecutableQueryLike<G extends GraphDef, R> {
+    toAst(): QueryAst;
+}
+/**
+ * Internal state for unionable query.
+ */
+type UnionableQueryState = Readonly<{
+    left: ComposableQuery;
+    operator: SetOperationType;
+    right: ComposableQuery;
+    limit?: number;
+    offset?: number;
+    startAlias?: string;
+    traversals?: readonly Traversal[];
+    selectFn?: (context: SelectContext<AliasMap, EdgeAliasMap>) => unknown;
+}>;
+/**
+ * A query formed by combining multiple queries with set operations.
+ * Supports chaining: q1.union(q2).intersect(q3)
+ */
+declare class UnionableQuery<G extends GraphDef, R> {
+    #private;
+    constructor(config: QueryBuilderConfig, state: UnionableQueryState);
+    /**
+     * Combines with another query using UNION.
+     */
+    union(other: ExecutableQueryLike<G, R>): UnionableQuery<G, R>;
+    /**
+     * Combines with another query using UNION ALL.
+     */
+    unionAll(other: ExecutableQueryLike<G, R>): UnionableQuery<G, R>;
+    /**
+     * Combines with another query using INTERSECT.
+     */
+    intersect(other: ExecutableQueryLike<G, R>): UnionableQuery<G, R>;
+    /**
+     * Combines with another query using EXCEPT.
+     */
+    except(other: ExecutableQueryLike<G, R>): UnionableQuery<G, R>;
+    /**
+     * Limits the number of results from the combined query.
+     */
+    limit(n: number): UnionableQuery<G, R>;
+    /**
+     * Offsets the results from the combined query.
+     */
+    offset(n: number): UnionableQuery<G, R>;
+    /**
+     * Builds the set operation AST.
+     */
+    toAst(): SetOperation;
+    /**
+     * Compiles the set operation to SQL.
+     */
+    compile(): SQL;
+    /**
+     * Executes the combined query.
+     */
+    execute(): Promise<readonly R[]>;
+}
+
+/**
+ * ExecutableQuery - A query that can be executed, paginated, or streamed.
+ */
+
+/**
+ * A query that can be executed.
+ */
+declare class ExecutableQuery<G extends GraphDef, Aliases extends AliasMap, EdgeAliases extends EdgeAliasMap = {}, R = unknown> {
+    #private;
+    constructor(config: QueryBuilderConfig, state: QueryBuilderState, selectFunction: (context: SelectContext<Aliases, EdgeAliases>) => R);
+    /**
+     * Builds the query AST.
+     */
+    toAst(): QueryAst;
+    /**
+     * Orders results.
+     */
+    orderBy<A extends keyof Aliases & string>(alias: A, field: string, direction?: SortDirection): ExecutableQuery<G, Aliases, EdgeAliases, R>;
+    /**
+     * Limits the number of results.
+     */
+    limit(n: number): ExecutableQuery<G, Aliases, EdgeAliases, R>;
+    /**
+     * Offsets the results.
+     */
+    offset(n: number): ExecutableQuery<G, Aliases, EdgeAliases, R>;
+    /**
+     * Applies a query fragment to transform this executable query.
+     *
+     * Useful for applying post-select transformations like ordering,
+     * limits, and offsets from reusable fragments.
+     *
+     * @example
+     * ```typescript
+     * const paginated = (q) => q.orderBy("u", "createdAt", "desc").limit(10);
+     *
+     * const results = await query()
+     *   .from("User", "u")
+     *   .select((ctx) => ctx.u)
+     *   .pipe(paginated)
+     *   .execute();
+     * ```
+     *
+     * @param fragment - A function that transforms the executable query
+     * @returns The transformed executable query
+     */
+    pipe<NewR = R>(fragment: (query: ExecutableQuery<G, Aliases, EdgeAliases, R>) => ExecutableQuery<G, Aliases, EdgeAliases, NewR>): ExecutableQuery<G, Aliases, EdgeAliases, NewR>;
+    /**
+     * Combines this query with another using UNION (removes duplicates).
+     */
+    union(other: ExecutableQuery<G, any, any, R>): UnionableQuery<G, R>;
+    /**
+     * Combines this query with another using UNION ALL (keeps duplicates).
+     */
+    unionAll(other: ExecutableQuery<G, any, any, R>): UnionableQuery<G, R>;
+    /**
+     * Combines this query with another using INTERSECT.
+     */
+    intersect(other: ExecutableQuery<G, any, any, R>): UnionableQuery<G, R>;
+    /**
+     * Combines this query with another using EXCEPT.
+     */
+    except(other: ExecutableQuery<G, any, any, R>): UnionableQuery<G, R>;
+    /**
+     * Compiles the query to a Drizzle SQL object.
+     *
+     * Returns a Drizzle SQL object that can be executed directly
+     * with db.all(), db.get(), etc.
+     */
+    compile(): SQL;
+    /**
+     * Executes the query and returns typed results.
+     *
+     * Uses smart optimization to detect when only specific fields are accessed
+     * in the select callback. If the callback only accesses simple field
+     * references (no method calls or computations), generates optimized SQL
+     * that only extracts those fields instead of the full props blob.
+     *
+     * @throws Error if no backend is configured
+     */
+    execute(): Promise<readonly R[]>;
+    /**
+     * Executes a paginated query using cursor-based keyset pagination.
+     *
+     * Cursor pagination is efficient for large datasets as it avoids OFFSET.
+     * Requires ORDER BY to be specified for deterministic results.
+     *
+     * @param options - Pagination options (first/after for forward, last/before for backward)
+     * @throws ValidationError if ORDER BY is not specified
+     * @throws ValidationError if cursor columns don't match query ORDER BY columns
+     */
+    paginate(options: PaginateOptions): Promise<PaginatedResult<R>>;
+    /**
+     * Returns an async iterator that streams results in batches.
+     *
+     * Uses cursor pagination internally for efficient memory usage.
+     * Requires ORDER BY to be specified for deterministic results.
+     *
+     * @param options - Stream options (batchSize defaults to 1000)
+     * @throws ValidationError if ORDER BY is not specified
+     */
+    stream(options?: StreamOptions): AsyncIterable<R>;
+}
+
+/**
+ * TraversalBuilder - Intermediate builder for edge traversals.
+ */
+
+/**
+ * State for variable-length traversal configuration.
+ */
+interface VariableLengthState {
+    enabled: boolean;
+    minDepth: number;
+    maxDepth: number;
+    collectPath: boolean;
+    pathAlias?: string;
+    depthAlias?: string;
+}
+/**
+ * Intermediate builder for traversal operations.
+ *
+ * Type parameters track the edge kind and direction to constrain
+ * which node kinds are valid targets in the `to()` method.
+ */
+declare class TraversalBuilder<G extends GraphDef, Aliases extends AliasMap, EdgeAliases extends EdgeAliasMap = {}, EK extends keyof G["edges"] & string = keyof G["edges"] & string, EA extends string = string, Dir extends TraversalDirection = "out", Optional extends boolean = false> {
+    #private;
+    constructor(config: QueryBuilderConfig, state: QueryBuilderState, edgeKinds: readonly string[], edgeAlias: EA, direction: Dir, fromAlias: string, optional?: Optional, variableLength?: VariableLengthState, pendingEdgePredicates?: readonly NodePredicate[]);
+    /**
+     * Enables variable-length (recursive) traversal.
+     * By default, traverses unlimited depth with cycle detection.
+     */
+    recursive(): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, Dir, Optional>;
+    /**
+     * Sets the maximum traversal depth.
+     * @param max Maximum number of hops (must be >= 1)
+     */
+    maxHops(max: number): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, Dir, Optional>;
+    /**
+     * Sets the minimum traversal depth (skip nodes closer than this).
+     * @param min Minimum hops before including results (default: 1)
+     */
+    minHops(min: number): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, Dir, Optional>;
+    /**
+     * Includes the traversal path as an array in results.
+     * @param alias Column alias for the path array (default: "{nodeAlias}_path")
+     */
+    collectPath(alias?: string): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, Dir, Optional>;
+    /**
+     * Includes the traversal depth in results.
+     * @param alias Column alias for the depth (default: "{nodeAlias}_depth")
+     */
+    withDepth(alias?: string): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, Dir, Optional>;
+    /**
+     * Adds a WHERE clause for the edge being traversed.
+     *
+     * @param alias - The edge alias to filter on (must be the current edge alias)
+     * @param predicateFunction - A function that builds predicates using the edge accessor
+     */
+    whereEdge(alias: EA, predicateFunction: (edge: EdgeAccessor<G["edges"][EK]["type"]>) => Predicate): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, Dir, Optional>;
+    /**
+     * Specifies the target node kind.
+     *
+     * The kind must be a valid target for this edge based on the traversal direction:
+     * - "out" direction: kind must be in the edge's "to" array
+     * - "in" direction: kind must be in the edge's "from" array
+     *
+     * @param kind - The target node kind
+     * @param alias - A unique alias for this node (compile-time error if duplicate)
+     */
+    to<K extends ValidEdgeTargets<G, EK, Dir>, A extends string>(kind: K, alias: UniqueAlias<A, Aliases>, options?: {
+        includeSubClasses?: false;
+    }): QueryBuilder<G, Aliases & Record<A, NodeAlias<G["nodes"][K]["type"], Optional>>, EdgeAliases & Record<EA, EdgeAlias<G["edges"][EK]["type"], Optional>>>;
+    to<K extends ValidEdgeTargets<G, EK, Dir>, A extends string>(kind: K, alias: UniqueAlias<A, Aliases>, options: {
+        includeSubClasses: true;
+    }): QueryBuilder<G, Aliases & Record<A, NodeAlias<NodeType, Optional>>, EdgeAliases & Record<EA, EdgeAlias<G["edges"][EK]["type"], Optional>>>;
+}
+
+/**
+ * QueryBuilder - The fluent query builder.
+ */
+
+/**
+ * The fluent query builder.
+ *
+ * Type parameters accumulate as methods are chained:
+ * - G: The graph definition
+ * - Aliases: Map of alias names to their node kinds
+ * - EdgeAliases: Map of alias names to their edge kinds (accumulated during traversals)
+ */
+declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = {}, EdgeAliases extends EdgeAliasMap = {}> {
+    #private;
+    constructor(config: QueryBuilderConfig, state: QueryBuilderState);
+    /**
+     * Starts a query from a node kind.
+     *
+     * @param kind - The node kind to start from
+     * @param alias - A unique alias for this node (compile-time error if duplicate)
+     */
+    from<K extends keyof G["nodes"] & string, A extends string>(kind: K, alias: UniqueAlias<A, Aliases>, options?: {
+        includeSubClasses?: false;
+    }): QueryBuilder<G, Aliases & Record<A, NodeAlias<G["nodes"][K]["type"]>>, EdgeAliases>;
+    from<K extends keyof G["nodes"] & string, A extends string>(kind: K, alias: UniqueAlias<A, Aliases>, options: {
+        includeSubClasses: true;
+    }): QueryBuilder<G, Aliases & Record<A, NodeAlias>, EdgeAliases>;
+    /**
+     * Adds a WHERE clause for a node.
+     */
+    whereNode<A extends keyof Aliases & string>(alias: A, predicateFunction: (n: NodeAccessor<Aliases[A]["kind"]>) => Predicate): QueryBuilder<G, Aliases, EdgeAliases>;
+    /**
+     * Adds a WHERE clause for an edge.
+     *
+     * @param alias - The edge alias to filter on
+     * @param predicateFunction - A function that builds predicates using the edge accessor
+     */
+    whereEdge<EA extends keyof EdgeAliases & string>(alias: EA, predicateFunction: (edge: EdgeAccessor<EdgeAliases[EA]["kind"]>) => Predicate): QueryBuilder<G, Aliases, EdgeAliases>;
+    /**
+     * Traverses an edge to another node (outgoing direction).
+     *
+     * By default, traverses from the current node (last traversal target, or start node).
+     * Use the `from` option to traverse from a different alias (fan-out pattern).
+     *
+     * @param options.includeImplyingEdges - If true, also match edges that imply this edge kind
+     * @param options.from - Alias to traverse from (defaults to current/last traversal target)
+     */
+    traverse<EK extends keyof G["edges"] & string, EA extends string>(edgeKind: EK, edgeAlias: EA, options?: {
+        direction?: "out";
+        includeImplyingEdges?: boolean;
+        from?: keyof Aliases & string;
+    }): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA>;
+    /**
+     * Traverses an edge to another node (incoming direction).
+     *
+     * By default, traverses from the current node (last traversal target, or start node).
+     * Use the `from` option to traverse from a different alias (fan-out pattern).
+     *
+     * @param options.direction - Set to "in" for incoming edge traversal
+     * @param options.includeImplyingEdges - If true, also match edges that imply this edge kind
+     * @param options.from - Alias to traverse from (defaults to current/last traversal target)
+     */
+    traverse<EK extends keyof G["edges"] & string, EA extends string>(edgeKind: EK, edgeAlias: EA, options: {
+        direction: "in";
+        includeImplyingEdges?: boolean;
+        from?: keyof Aliases & string;
+    }): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, "in">;
+    /**
+     * Optionally traverses an edge to another node (LEFT JOIN semantics).
+     * If no matching edge/node exists, the result will include null values.
+     *
+     * By default, traverses from the current node (last traversal target, or start node).
+     * Use the `from` option to traverse from a different alias (fan-out pattern).
+     *
+     * @param options.direction - Direction of traversal: "out" (default) or "in"
+     * @param options.includeImplyingEdges - If true, also match edges that imply this edge kind
+     * @param options.from - Alias to traverse from (defaults to current/last traversal target)
+     */
+    optionalTraverse<EK extends keyof G["edges"] & string, EA extends string>(edgeKind: EK, edgeAlias: EA, options?: {
+        direction?: "out";
+        includeImplyingEdges?: boolean;
+        from?: keyof Aliases & string;
+    }): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, "out", true>;
+    optionalTraverse<EK extends keyof G["edges"] & string, EA extends string>(edgeKind: EK, edgeAlias: EA, options: {
+        direction: "in";
+        includeImplyingEdges?: boolean;
+        from?: keyof Aliases & string;
+    }): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, "in", true>;
+    /**
+     * Selects fields to return.
+     */
+    select<R>(selectFunction: (context: SelectContext<Aliases, EdgeAliases>) => R): ExecutableQuery<G, Aliases, EdgeAliases, R>;
+    /**
+     * Selects fields including aggregates.
+     * Use with groupBy() for aggregate queries.
+     *
+     * @param fields - Object mapping output names to field refs or aggregate expressions
+     */
+    selectAggregate<R extends Record<string, FieldRef | AggregateExpr>>(fields: R): ExecutableAggregateQuery<G, Aliases, R>;
+    /**
+     * Orders results.
+     */
+    orderBy<A extends keyof Aliases & string>(alias: A, field: string, direction?: SortDirection): QueryBuilder<G, Aliases, EdgeAliases>;
+    /**
+     * Limits the number of results.
+     */
+    limit(n: number): QueryBuilder<G, Aliases, EdgeAliases>;
+    /**
+     * Offsets the results.
+     */
+    offset(n: number): QueryBuilder<G, Aliases, EdgeAliases>;
+    /**
+     * Sets temporal mode.
+     *
+     * @param mode - The temporal mode to use
+     * @param asOf - Required timestamp for "asOf" mode (ISO 8601 string)
+     * @throws ValidationError if mode is "asOf" but no timestamp is provided
+     */
+    temporal(mode: TemporalMode, asOf?: string): QueryBuilder<G, Aliases, EdgeAliases>;
+    /**
+     * Groups results by the specified field.
+     * Use with aggregate functions like COUNT, SUM, AVG in select().
+     *
+     * @param alias - The node alias to group by
+     * @param field - The field name to group by
+     */
+    groupBy<A extends keyof Aliases & string>(alias: A, field: string): QueryBuilder<G, Aliases, EdgeAliases>;
+    /**
+     * Groups results by the node ID.
+     * Use when you want to group by a complete node rather than a specific field.
+     *
+     * @param alias - The node alias to group by (uses the node's ID)
+     */
+    groupByNode<A extends keyof Aliases & string>(alias: A): QueryBuilder<G, Aliases, EdgeAliases>;
+    /**
+     * Filters grouped results using aggregate conditions (HAVING clause).
+     * Use after groupBy() to filter based on aggregate values.
+     *
+     * @param predicate - A predicate expression to filter groups
+     */
+    having(predicate: PredicateExpression): QueryBuilder<G, Aliases, EdgeAliases>;
+    /**
+     * Applies a query fragment to transform this builder.
+     *
+     * Fragments are reusable query transformations that can add predicates,
+     * traversals, ordering, and other query operations. Use this for
+     * composing complex queries from simpler, reusable parts.
+     *
+     * @example
+     * ```typescript
+     * // Define a reusable fragment
+     * const activeUsers = createFragment<MyGraph>()((q) =>
+     *   q.whereNode("u", ({ status }) => status.eq("active"))
+     * );
+     *
+     * // Apply the fragment
+     * const results = await query()
+     *   .from("User", "u")
+     *   .pipe(activeUsers)
+     *   .select((ctx) => ctx.u)
+     *   .execute();
+     * ```
+     *
+     * @param fragment - A function that transforms the builder
+     * @returns The transformed builder
+     */
+    pipe<OutAliases extends AliasMap, OutEdgeAliases extends EdgeAliasMap = EdgeAliases>(fragment: (builder: QueryBuilder<G, Aliases, EdgeAliases>) => QueryBuilder<G, OutAliases, OutEdgeAliases>): QueryBuilder<G, OutAliases, OutEdgeAliases>;
+}
+
+/**
+ * Types for serialized schema storage.
+ *
+ * These types represent the JSON-serializable format used for
+ * homoiconic schema storage in the database.
+ */
+
+/**
+ * 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<{
+    name: string;
+    properties: JsonSchema;
+    uniqueConstraints: readonly SerializedUniqueConstraint[];
+    onDelete: DeleteBehavior;
+    description: string | undefined;
+}>;
+/**
+ * Serialized representation of an edge kind.
+ */
+type SerializedEdgeDef = Readonly<{
+    name: string;
+    fromKinds: readonly string[];
+    toKinds: readonly string[];
+    properties: JsonSchema;
+    cardinality: Cardinality;
+    endpointExistence: EndpointExistence;
+    description: string | undefined;
+}>;
+/**
+ * Complete serialized schema document.
+ *
+ * This is the format stored in the schema_doc column of
+ * typegraph_schema_versions.
+ */
+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;
+    }>;
+}>;
+/**
+ * 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;
+
+/**
+ * Schema migration utilities.
+ *
+ * Provides diff detection between schema versions to identify
+ * what has changed and what migrations might be needed.
+ */
+
+/**
+ * Types of changes that can occur in a schema.
+ */
+type ChangeType = "added" | "removed" | "modified" | "renamed";
+/**
+ * Severity of a change for migration purposes.
+ */
+type ChangeSeverity = "safe" | "warning" | "breaking";
+/**
+ * A change to a node definition.
+ */
+type NodeChange = Readonly<{
+    type: ChangeType;
+    name: string;
+    severity: ChangeSeverity;
+    details: string;
+    before?: SerializedNodeDef | undefined;
+    after?: SerializedNodeDef | undefined;
+}>;
+/**
+ * A change to an edge definition.
+ */
+type EdgeChange = Readonly<{
+    type: ChangeType;
+    name: string;
+    severity: ChangeSeverity;
+    details: string;
+    before?: SerializedEdgeDef | undefined;
+    after?: SerializedEdgeDef | undefined;
+}>;
+/**
+ * A change to the ontology.
+ */
+type OntologyChange = Readonly<{
+    type: ChangeType;
+    entity: "metaEdge" | "relation";
+    name: string;
+    severity: ChangeSeverity;
+    details: string;
+}>;
+/**
+ * A complete diff between two schema versions.
+ */
+type SchemaDiff = Readonly<{
+    fromVersion: number;
+    toVersion: number;
+    /** Changes to node definitions */
+    nodes: readonly NodeChange[];
+    /** Changes to edge definitions */
+    edges: readonly EdgeChange[];
+    /** Changes to ontology */
+    ontology: readonly OntologyChange[];
+    /** Whether any breaking changes exist */
+    hasBreakingChanges: boolean;
+    /** Whether any changes exist at all */
+    hasChanges: boolean;
+    /** Summary of changes */
+    summary: string;
+}>;
+/**
+ * Computes the diff between two schema versions.
+ *
+ * @param before - The previous schema version
+ * @param after - The new schema version
+ * @returns A diff describing all changes
+ */
+declare function computeSchemaDiff(before: SerializedSchema, after: SerializedSchema): SchemaDiff;
+/**
+ * Checks if a schema change is backwards compatible.
+ *
+ * A change is backwards compatible if:
+ * - No nodes or edges were removed
+ * - No required properties were added
+ * - No existing properties were removed
+ */
+declare function isBackwardsCompatible(diff: SchemaDiff): boolean;
+/**
+ * Gets a list of actions needed for migration.
+ */
+declare function getMigrationActions(diff: SchemaDiff): readonly string[];
+
+/**
+ * Schema manager for TypeGraph.
+ *
+ * Provides schema lifecycle management:
+ * - Initialization on first store creation
+ * - Validation on store open
+ * - Auto-migration for safe changes
+ * - Error reporting for breaking changes
+ */
+
+/**
+ * Result of schema validation.
+ */
+type SchemaValidationResult = {
+    status: "initialized";
+    version: number;
+} | {
+    status: "unchanged";
+    version: number;
+} | {
+    status: "migrated";
+    fromVersion: number;
+    toVersion: number;
+    diff: SchemaDiff;
+} | {
+    status: "breaking";
+    diff: SchemaDiff;
+    actions: readonly string[];
+};
+/**
+ * Options for schema management.
+ */
+type SchemaManagerOptions = Readonly<{
+    /** If true, auto-migrate safe changes. Default: true */
+    autoMigrate?: boolean;
+    /** If true, throw on breaking changes. Default: true */
+    throwOnBreaking?: boolean;
+}>;
+/**
+ * Ensures the schema is initialized and up-to-date.
+ *
+ * This is the main entry point for schema management. It:
+ * 1. Initializes the schema if this is the first run (version 1)
+ * 2. Returns "unchanged" if the schema matches the current graph
+ * 3. Auto-migrates safe changes if autoMigrate is true
+ * 4. Throws MigrationError for breaking changes if throwOnBreaking is true
+ *
+ * @param backend - The database backend
+ * @param graph - The current graph definition
+ * @param options - Schema management options
+ * @returns The result of schema validation
+ * @throws MigrationError if breaking changes detected and throwOnBreaking is true
+ */
+declare function ensureSchema<G extends GraphDef>(backend: GraphBackend, graph: G, options?: SchemaManagerOptions): Promise<SchemaValidationResult>;
+/**
+ * Initializes the schema for a new graph.
+ *
+ * Creates version 1 of the schema and marks it as active.
+ *
+ * @param backend - The database backend
+ * @param graph - The graph definition
+ * @returns The created schema version row
+ */
+declare function initializeSchema<G extends GraphDef>(backend: GraphBackend, graph: G): Promise<SchemaVersionRow>;
+/**
+ * Migrates the schema to match the current graph definition.
+ *
+ * This creates a new schema version and marks it as active.
+ * The old version is preserved for history/rollback.
+ *
+ * @param backend - The database backend
+ * @param graph - The current graph definition
+ * @param currentVersion - The current active schema version
+ * @returns The new version number
+ */
+declare function migrateSchema<G extends GraphDef>(backend: GraphBackend, graph: G, currentVersion: number): Promise<number>;
+/**
+ * Gets the current active schema for a graph.
+ *
+ * @param backend - The database backend
+ * @param graphId - The graph ID
+ * @returns The active schema or undefined if not initialized
+ */
+declare function getActiveSchema(backend: GraphBackend, graphId: string): Promise<SerializedSchema | undefined>;
+/**
+ * Checks if a graph's schema has been initialized.
+ *
+ * @param backend - The database backend
+ * @param graphId - The graph ID
+ * @returns True if the schema has been initialized
+ */
+declare function isSchemaInitialized(backend: GraphBackend, graphId: string): Promise<boolean>;
+/**
+ * Gets the schema diff between the stored schema and current graph.
+ *
+ * @param backend - The database backend
+ * @param graph - The current graph definition
+ * @returns The diff, or undefined if schema not initialized
+ */
+declare function getSchemaChanges<G extends GraphDef>(backend: GraphBackend, graph: G): Promise<SchemaDiff | undefined>;
+
+/**
+ * Main Store implementation for TypeGraph.
+ *
+ * The Store is the primary interface for interacting with a TypeGraph.
+ * It coordinates:
+ * - Node and edge CRUD operations
+ * - Constraint validation
+ * - Schema management
+ * - Transaction handling
+ */
+
+/**
+ * The Store provides typed access to a TypeGraph database.
+ *
+ * @example
+ * ```typescript
+ * const store = createStore(myGraph, backend);
+ *
+ * // Create nodes using collection API
+ * const person = await store.nodes.Person.create({
+ *   name: "Alice",
+ *   email: "alice@example.com",
+ * });
+ *
+ * const company = await store.nodes.Company.create({
+ *   name: "Acme",
+ *   industry: "Technology",
+ * });
+ *
+ * // Create edges
+ * await store.edges.worksAt.create(
+ *   { kind: "Person", id: person.id },
+ *   { kind: "Company", id: company.id },
+ *   { role: "Engineer" }
+ * );
+ *
+ * // Query with the fluent API
+ * const results = await store.query()
+ *   .from("Person", "p")
+ *   .whereNode("p", (p) => p.name.eq("Alice"))
+ *   .select((ctx) => ctx.p)
+ *   .execute();
+ * ```
+ */
+declare class Store<G extends GraphDef> {
+    #private;
+    constructor(graph: G, backend: GraphBackend, options?: StoreOptions);
+    /** The graph definition */
+    get graph(): G;
+    /** The graph ID */
+    get graphId(): string;
+    /** The kind registry for ontology lookups */
+    get registry(): KindRegistry;
+    /** The database backend */
+    get backend(): GraphBackend;
+    /**
+     * Node collections for ergonomic CRUD operations.
+     *
+     * @example
+     * ```typescript
+     * // Create a node
+     * const person = await store.nodes.Person.create({ name: "Alice" });
+     *
+     * // Get by ID
+     * const fetched = await store.nodes.Person.getById(person.id);
+     *
+     * // Find all
+     * const people = await store.nodes.Person.find({ limit: 10 });
+     * ```
+     */
+    get nodes(): {
+        [K in keyof G["nodes"] & string]-?: NodeCollection<G["nodes"][K]["type"]>;
+    };
+    /**
+     * Edge collections for ergonomic CRUD operations.
+     *
+     * @example
+     * ```typescript
+     * // Create an edge
+     * const edge = await store.edges.worksAt.create(
+     *   { kind: "Person", id: person.id },
+     *   { kind: "Company", id: company.id },
+     *   { role: "Engineer" }
+     * );
+     *
+     * // Find edges from a node
+     * const edges = await store.edges.worksAt.findFrom({ kind: "Person", id: person.id });
+     * ```
+     */
+    get edges(): {
+        [K in keyof G["edges"] & string]-?: TypedEdgeCollection<G["edges"][K]>;
+    };
+    /**
+     * Creates a query builder for this store.
+     *
+     * @example
+     * ```typescript
+     * const results = await store.query()
+     *   .from("Person", "p")
+     *   .whereNode("p", (p) => p.name.eq("Alice"))
+     *   .select((ctx) => ctx.p)
+     *   .execute();
+     * ```
+     */
+    query(): QueryBuilder<G>;
+    /**
+     * Executes a function within a transaction.
+     *
+     * The transaction context provides the same collection API as the Store:
+     * - `tx.nodes.Person.create(...)` - Create a node
+     * - `tx.edges.worksAt.create(...)` - Create an edge
+     *
+     * @example
+     * ```typescript
+     * await store.transaction(async (tx) => {
+     *   const person = await tx.nodes.Person.create({ name: "Alice" });
+     *   const company = await tx.nodes.Company.create({ name: "Acme" });
+     *   await tx.edges.worksAt.create(
+     *     { kind: "Person", id: person.id },
+     *     { kind: "Company", id: company.id },
+     *     { role: "Engineer" }
+     *   );
+     * });
+     * ```
+     */
+    transaction<T>(fn: (tx: TransactionContext<G>) => Promise<T>): Promise<T>;
+    /**
+     * Closes the store and releases underlying resources.
+     *
+     * Note: When using the Drizzle adapter, this method does not close the database
+     * connection itself, as Drizzle delegates connection management to the user.
+     * You should close the underlying database connection (e.g., better-sqlite3 or pg pool)
+     * using their respective APIs.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Creates a new Store instance.
+ *
+ * @param graph - The graph definition
+ * @param backend - The database backend
+ * @param options - Optional store configuration including observability hooks
+ * @returns A new Store instance
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const store = createStore(graph, backend);
+ *
+ * // With observability hooks
+ * const store = createStore(graph, backend, {
+ *   hooks: {
+ *     onOperationStart: (ctx) => {
+ *       console.log(`Starting ${ctx.operation} on ${ctx.entity}:${ctx.kind}`);
+ *     },
+ *     onOperationEnd: (ctx, result) => {
+ *       console.log(`Completed in ${result.durationMs}ms`);
+ *     },
+ *     onError: (ctx, error) => {
+ *       console.error(`Operation ${ctx.operationId} failed:`, error);
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare function createStore<G extends GraphDef>(graph: G, backend: GraphBackend, options?: StoreOptions): Store<G>;
+
+/**
+ * Creates a store and ensures the schema is initialized/migrated.
+ *
+ * This is the recommended way to create a store in production.
+ * It automatically:
+ * - Initializes the schema on first run (version 1)
+ * - Auto-migrates safe changes (additive changes)
+ * - Throws MigrationError for breaking changes
+ *
+ * @param graph - The graph definition
+ * @param backend - The database backend
+ * @param options - Store and schema options
+ * @returns A tuple of [store, validationResult]
+ *
+ * @example
+ * ```typescript
+ * const [store, result] = await createStoreWithSchema(graph, backend);
+ *
+ * if (result.status === "initialized") {
+ *   console.log("Schema initialized at version", result.version);
+ * } else if (result.status === "migrated") {
+ *   console.log(`Migrated from v${result.fromVersion} to v${result.toVersion}`);
+ * }
+ * ```
+ */
+declare function createStoreWithSchema<G extends GraphDef>(graph: G, backend: GraphBackend, options?: StoreOptions & SchemaManagerOptions): Promise<[Store<G>, SchemaValidationResult]>;
+
+export { type QueryOptions as $, type AliasMap as A, type NodeAlias as B, type CreateQueryBuilderOptions as C, type NodeChange as D, type EdgeAliasMap as E, type FieldAccessor as F, type GraphDef as G, type HookContext as H, type InferenceType as I, type JsonSchema as J, KindRegistry as K, type NodeCollection as L, type MetaEdge as M, type Node as N, type OntologyRelation as O, type NodeRef as P, QueryBuilder as Q, type NodeTypeNames as R, Store as S, TraversalBuilder as T, type OntologyChange as U, type OperationHookContext as V, type PaginateOptions as W, type PaginatedResult as X, type Predicate as Y, type PropsAccessor as Z, type QueryHookContext as _, type SerializedNodeDef as a, type SchemaDiff as a0, type SchemaManagerOptions as a1, type SchemaValidationResult as a2, type SelectContext as a3, type SelectableEdge as a4, type SelectableNode as a5, type SerializedOntology as a6, type SerializedUniqueConstraint as a7, type StoreConfig as a8, type StoreHooks as a9, isMetaEdge as aA, isSchemaInitialized as aB, migrateSchema as aC, notExists as aD, notInSubquery as aE, type StoreOptions as aa, type StreamOptions as ab, type TransactionContext as ac, type TypedEdgeCollection as ad, type TypedNodeRef as ae, type UpdateEdgeInput as af, type UpdateNodeInput as ag, computeSchemaDiff as ah, createStore as ai, createStoreWithSchema as aj, defineGraph as ak, embedding as al, ensureSchema as am, exists as an, fieldRef as ao, getActiveSchema as ap, getEdgeTypeNames as aq, getEmbeddingDimensions as ar, getMigrationActions as as, getNodeTypeNames as at, getSchemaChanges as au, inSubquery as av, initializeSchema as aw, isBackwardsCompatible as ax, isEmbeddingSchema as ay, isGraphDef as az, type SerializedEdgeDef as b, type SerializedMetaEdge as c, type SerializedOntologyRelation as d, type SerializedClosures as e, type SerializedSchema as f, type SchemaHash as g, type AllEdgeTypes as h, type AllNodeTypes as i, type ChangeSeverity as j, type ChangeType as k, type CreateEdgeInput as l, type CreateNodeInput as m, type Edge as n, type EdgeAccessor as o, type EdgeChange as p, type EdgeCollection as q, type EdgeTypeNames as r, type EmbeddingSchema as s, type EmbeddingValue as t, ExecutableAggregateQuery as u, ExecutableQuery as v, type GetEdgeType as w, type GetNodeType as x, type MetaEdgeProperties as y, type NodeAccessor as z };