@nicia-ai/typegraph 0.2.0 → 0.3.0

package/dist/{store-BPhjw5S8.d.ts → store-DM3Tk3Pw.d.ts}

@@ -1,59 +1,11 @@
-import { S as SqlSchema, G as GraphBackend, b as SchemaVersionRow } from './types-DsRfx0yk.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 { k as SqlSchema, G as GraphBackend } from './types-Cdbi4hcx.js';
+import { K as KindRegistry, G as GraphDef, b as SchemaManagerOptions, c as SchemaValidationResult } from './manager-e9LXthrx.js';
+import { N as NodeType, A as AnyEdgeType, T as TemporalMode, E as EdgeType, b as EdgeRegistration, g as NodeId } from './types-DTJEu_-h.js';
+import { V as ValueType, i as PredicateExpression, k as VectorMetricType, Q as QueryAst, J as JsonPointer, F as FieldRef, P as ParameterRef, d as JsonPointerInput, T as TraversalExpansion, l as Traversal, N as NodePredicate, m as ProjectedField, O as OrderSpec, G as GroupBySpec, o as RecursiveCyclePolicy, q as TraversalDirection, A as AggregateExpr, r as SelectiveField, s as ComposableQuery, t as SetOperationType, u as SetOperation, S as SortDirection } from './ast-CXFx6bF6.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.
  *
@@ -135,479 +87,711 @@ declare function isEmbeddingSchema(value: unknown): value is EmbeddingSchema;
  */
 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.
+ * Query Compiler Module
+ *
+ * Main entry point for compiling query ASTs to SQL.
+ * Re-exports individual compiler modules and provides the main compile functions.
  */
-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.
+ * Options for query compilation.
  */
-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;
+type CompileQueryOptions = Readonly<{
+    /** SQL dialect ("sqlite" or "postgres"). Defaults to "sqlite". */
+    dialect?: SqlDialect | undefined;
+    /** SQL schema configuration for table names. Defaults to standard names. */
+    schema?: SqlSchema | undefined;
 }>;
-/**
- * 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;
-    }>;
+
+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;
+}>;
+
 /**
- * Extract node type names from a GraphDef.
- */
-type NodeTypeNames<G extends GraphDef> = keyof G["nodes"] & string;
-/**
- * Extract edge type names from a GraphDef.
+ * A chainable predicate that can be combined with AND/OR.
  */
-type EdgeTypeNames<G extends GraphDef> = keyof G["edges"] & string;
+type Predicate = Readonly<{
+    __expr: PredicateExpression;
+    and: (other: Predicate) => Predicate;
+    or: (other: Predicate) => Predicate;
+    not: () => Predicate;
+}>;
 /**
- * Get a NodeType from a GraphDef by name.
+ * Creates a named parameter reference for prepared queries.
+ *
+ * Use with `query.prepare()` to create reusable parameterized queries.
+ * Only supported in scalar comparison positions (eq, neq, gt, etc.),
+ * string operations, and between bounds. Not supported in `in()`/`notIn()`.
+ *
+ * @example
+ * ```typescript
+ * const prepared = store.query()
+ *   .from("Person", "p")
+ *   .whereNode("p", (p) => p.name.eq(param("name")))
+ *   .select((ctx) => ctx.p)
+ *   .prepare();
+ *
+ * const results = await prepared.execute({ name: "Alice" });
+ * ```
  */
-type GetNodeType<G extends GraphDef, K extends NodeTypeNames<G>> = G["nodes"][K]["type"];
+declare function param(name: string): ParameterRef;
 /**
- * Get an EdgeType from a GraphDef by name.
+ * Type guard for ParameterRef values.
  */
-type GetEdgeType<G extends GraphDef, K extends EdgeTypeNames<G>> = G["edges"][K]["type"];
+declare function isParameterRef(value: unknown): value is ParameterRef;
 /**
- * Get all NodeTypes from a GraphDef.
+ * Options for the similarTo method.
  */
-type AllNodeTypes<G extends GraphDef> = {
-    [K in NodeTypeNames<G>]: G["nodes"][K]["type"];
-}[NodeTypeNames<G>];
+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;
+}>;
 /**
- * Get all EdgeTypes from a GraphDef.
+ * Creates a field reference.
  */
-type AllEdgeTypes<G extends GraphDef> = {
-    [K in EdgeTypeNames<G>]: G["edges"][K]["type"];
-}[EdgeTypeNames<G>];
+type FieldRefOptions = Readonly<{
+    jsonPointer?: JsonPointer | undefined;
+    valueType?: ValueType | undefined;
+    elementType?: ValueType | undefined;
+}>;
+declare function fieldRef(alias: string, path: readonly string[], options?: FieldRefOptions): FieldRef;
 /**
- * Creates a graph definition.
+ * 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
- * 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",
- *   },
- * });
+ * // 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 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>;
+declare function exists(subquery: QueryAst): Predicate;
 /**
- * Checks if a value is a GraphDef.
+ * 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 isGraphDef(value: unknown): value is GraphDef;
+declare function notExists(subquery: QueryAst): Predicate;
 /**
- * Gets all node type names from a GraphDef.
+ * 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")
+ *         .aggregate({
+ *           id: fieldRef("v", ["props", "personId"], { valueType: "string" }),
+ *         })
+ *         .toAst()
+ *     )
+ *   )
+ * ```
  */
-declare function getNodeTypeNames<G extends GraphDef>(graph: G): readonly string[];
+declare function inSubquery(field: FieldRef, subquery: QueryAst): Predicate;
 /**
- * Gets all edge type names from a GraphDef.
+ * 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 getEdgeTypeNames<G extends GraphDef>(graph: G): readonly string[];
+declare function notInSubquery(field: FieldRef, subquery: QueryAst): Predicate;
 
 /**
- * KindRegistry holds precomputed closures for ontological reasoning.
+ * Shared type definitions for the query builder.
  *
- * Computed at store initialization and cached for fast query-time lookups.
+ * Contains type definitions used across QueryBuilder, TraversalBuilder,
+ * and ExecutableQuery classes.
  */
-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;
-}
 
 /**
- * Store types for TypeGraph operations.
+ * 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]["kind"] : G["edges"][EK]["from"][number]["kind"] : never;
 /**
- * Metadata for a node instance.
+ * A node alias with its associated type.
  */
-type NodeMeta = Readonly<{
-    version: number;
-    validFrom: string | undefined;
-    validTo: string | undefined;
-    createdAt: string;
-    updatedAt: string;
-    deletedAt: string | undefined;
+type NodeAlias<K extends NodeType = NodeType, Optional extends boolean = false> = Readonly<{
+    type: K;
+    alias: string;
+    optional: Optional;
 }>;
 /**
- * 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.*`
+ * A map of alias names to their node aliases.
  */
-type Node<N extends NodeType = NodeType> = Readonly<{
-    kind: N["name"];
-    id: NodeId<N>;
-    meta: NodeMeta;
-}> & Readonly<z.infer<N["schema"]>>;
+type AliasMap = Readonly<Record<string, NodeAlias<NodeType, boolean>>>;
 /**
- * Input for creating a node.
+ * An edge alias with its associated type and optional flag.
  */
-type CreateNodeInput<N extends NodeType = NodeType> = Readonly<{
-    kind: N["name"];
-    id?: string;
-    props: z.infer<N["schema"]>;
-    validFrom?: string;
-    validTo?: string;
+type EdgeAlias<E extends AnyEdgeType = EdgeType, Optional extends boolean = false> = Readonly<{
+    type: E;
+    alias: string;
+    optional: Optional;
 }>;
 /**
- * Input for updating a node.
+ * A map of alias names to their edge aliases.
  */
-type UpdateNodeInput<N extends NodeType = NodeType> = Readonly<{
-    kind: N["name"];
-    id: NodeId<N>;
-    props: Partial<z.infer<N["schema"]>>;
-    validTo?: string;
-}>;
+type EdgeAliasMap = Readonly<Record<string, EdgeAlias<EdgeType, boolean>>>;
 /**
- * Metadata for an edge instance.
+ * A recursive alias marker with its associated type (depth or path).
  */
-type EdgeMeta = Readonly<{
-    validFrom: string | undefined;
-    validTo: string | undefined;
-    createdAt: string;
-    updatedAt: string;
-    deletedAt: string | undefined;
+type RecursiveAlias<T extends "depth" | "path"> = Readonly<{
+    type: T;
 }>;
 /**
- * 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.*`
+ * A map of recursive alias names to their types.
  */
-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"]>>;
+type RecursiveAliasMap = Readonly<Record<string, RecursiveAlias<"depth" | "path">>>;
 /**
- * Input for creating an edge.
+ * Resolves a recursive alias marker to its runtime value type.
  */
-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;
-}>;
+type RecursiveAliasValue<RA> = RA extends RecursiveAlias<"depth"> ? number : RA extends RecursiveAlias<"path"> ? readonly string[] : never;
 /**
- * Input for updating an edge.
+ * Resolves the depth alias name from the recursive config.
+ * If a string is provided, uses it directly. If `true`, defaults to `${A}_depth`.
  */
-type UpdateEdgeInput<E extends AnyEdgeType = EdgeType> = Readonly<{
-    id: string;
-    props: Partial<z.infer<E["schema"]>>;
-    validTo?: string;
+type ResolveDepthAlias<DC, A extends string> = DC extends string ? DC : DC extends true ? `${A}_depth` : never;
+/**
+ * Resolves the path alias name from the recursive config.
+ * If a string is provided, uses it directly. If `true`, defaults to `${A}_path`.
+ */
+type ResolvePathAlias<PC, A extends string> = PC extends string ? PC : PC extends true ? `${A}_path` : never;
+/**
+ * Builds the recursive alias map from depth/path config and target node alias.
+ */
+type BuildRecursiveAliases<DC, PC, A extends string> = ([DC] extends ([
+    false
+]) ? {} : Record<ResolveDepthAlias<DC, A>, RecursiveAlias<"depth">>) & ([PC] extends [false] ? {} : Record<ResolvePathAlias<PC, A>, RecursiveAlias<"path">>);
+/**
+ * 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]>;
 }>;
 /**
- * Options for node and edge queries.
+ * A field accessor with type-appropriate predicate methods.
+ * Uses NonNullable to handle optional fields correctly.
  */
-type QueryOptions = Readonly<{
-    /** Temporal mode for the query */
-    temporalMode?: TemporalMode;
-    /** Specific timestamp for asOf queries */
-    asOf?: string;
+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 | ParameterRef) => Predicate;
+    startsWith: (pattern: string | ParameterRef) => Predicate;
+    endsWith: (pattern: string | ParameterRef) => Predicate;
+    like: (pattern: string | ParameterRef) => Predicate;
+    ilike: (pattern: string | ParameterRef) => Predicate;
+}>;
+type NumberFieldAccessor = BaseFieldAccessor & Readonly<{
+    gt: (value: number | ParameterRef) => Predicate;
+    gte: (value: number | ParameterRef) => Predicate;
+    lt: (value: number | ParameterRef) => Predicate;
+    lte: (value: number | ParameterRef) => Predicate;
+    between: (lower: number | ParameterRef, upper: number | ParameterRef) => Predicate;
+}>;
+type BooleanFieldAccessor = BaseFieldAccessor;
+type DateFieldAccessor = BaseFieldAccessor & Readonly<{
+    gt: (value: Date | string | ParameterRef) => Predicate;
+    gte: (value: Date | string | ParameterRef) => Predicate;
+    lt: (value: Date | string | ParameterRef) => Predicate;
+    lte: (value: Date | string | ParameterRef) => Predicate;
+    between: (lower: Date | string | ParameterRef, upper: Date | string | ParameterRef) => 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;
 }>;
 /**
- * Context passed to observability hooks.
+ * 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 HookContext = Readonly<{
-    /** Unique ID for this operation */
-    operationId: string;
-    /** Graph ID */
-    graphId: string;
-    /** Timestamp when operation started */
-    startedAt: Date;
+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]>;
 }>;
 /**
- * Query hook context with SQL information.
+ * 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 QueryHookContext = HookContext & Readonly<{
-    /** The SQL query being executed */
-    sql: string;
-    /** Query parameters */
-    params: readonly unknown[];
+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;
 }>;
 /**
- * Operation hook context for CRUD operations.
+ * 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 OperationHookContext = HookContext & Readonly<{
-    /** Operation type */
-    operation: "create" | "update" | "delete";
-    /** Entity type */
-    entity: "node" | "edge";
-    /** Kind of node or edge */
-    kind: string;
-    /** Entity ID */
+type SelectableNode<N extends NodeType> = Readonly<{
     id: string;
+    kind: N["kind"];
+    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;
 }>;
 /**
- * Observability hooks for monitoring store operations.
+ * A selectable edge result.
  *
- * @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);
- *   },
- * };
+ * 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["kind"];
+    fromId: string;
+    toId: string;
+    meta: SelectableEdgeMeta;
+}> & Readonly<z.infer<E["schema"]>>;
+/**
+ * Selection context passed to select callback.
  *
- * const store = createStore(graph, backend, { hooks });
- * ```
+ * Includes node aliases, edge aliases, and recursive metadata aliases
+ * (depth/path from variable-length traversals). Edge aliases from optional
+ * traversals are nullable.
  */
-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;
+type SelectContext<Aliases extends AliasMap, EdgeAliases extends EdgeAliasMap = Record<string, never>, RecursiveAliases extends RecursiveAliasMap = {}> = Readonly<{
+    [A in keyof Aliases]: Aliases[A]["optional"] extends true ? SelectableNode<Aliases[A]["type"]> | undefined : SelectableNode<Aliases[A]["type"]>;
+}> & Readonly<{
+    [EA in keyof EdgeAliases]: EdgeAliases[EA]["optional"] extends true ? SelectableEdge<EdgeAliases[EA]["type"]> | undefined : SelectableEdge<EdgeAliases[EA]["type"]>;
+}> & Readonly<{
+    [RA in keyof RecursiveAliases]: RecursiveAliasValue<RecursiveAliases[RA]>;
 }>;
 /**
- * Options for creating a store.
+ * Result of a paginated query.
  */
-type StoreOptions = Readonly<{
-    /** Observability hooks for monitoring */
-    hooks?: StoreHooks;
-    /** SQL schema configuration for custom table names */
-    schema?: SqlSchema;
+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;
 }>;
 /**
- * Configuration for creating a store.
+ * Options for cursor-based pagination.
+ *
+ * Use `first`/`after` for forward pagination, `last`/`before` for backward.
  */
-type StoreConfig<G extends GraphDef> = Readonly<{
-    /** The graph definition */
-    graph: G;
-    /** Database connection string or path */
-    connection?: string;
-    /** Auto-run migrations */
-    autoMigrate?: boolean;
+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;
 }>;
 /**
- * A collection of nodes of a specific type.
- *
- * Provides ergonomic CRUD operations for a single node type.
+ * Options for streaming results.
  */
-type NodeCollection<N extends NodeType> = Readonly<{
-    /** Create a new node */
-    create: (props: z.input<N["schema"]>, options?: Readonly<{
-        id?: string;
+type StreamOptions = Readonly<{
+    /** Number of items to fetch per batch (default: 1000) */
+    batchSize?: number;
+}>;
+/**
+ * Options for recursive traversals.
+ */
+type RecursiveTraversalOptions = Readonly<{
+    /** Minimum number of hops before including results (default: 1) */
+    minHops?: number;
+    /** Maximum number of hops (-1 means unlimited) */
+    maxHops?: number;
+    /** Cycle handling policy (default: "prevent") */
+    cyclePolicy?: RecursiveCyclePolicy;
+    /** Include path in output. Pass a string to customize alias. */
+    path?: boolean | string;
+    /** Include depth in output. Pass a string to customize alias. */
+    depth?: boolean | string;
+}>;
+/**
+ * Configuration for the query builder.
+ */
+type QueryBuilderConfig = Readonly<{
+    graphId: string;
+    registry: KindRegistry;
+    schemaIntrospector: SchemaIntrospector;
+    /** Default traversal ontology expansion mode. */
+    defaultTraversalExpansion: TraversalExpansion;
+    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;
+    /** Default traversal ontology expansion mode (default: "inverse"). */
+    defaultTraversalExpansion?: TraversalExpansion;
+}>;
+
+/**
+ * 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["kind"];
+    id: NodeId<N>;
+    meta: NodeMeta;
+}> & Readonly<z.infer<N["schema"]>>;
+/**
+ * Input for creating a node.
+ */
+type CreateNodeInput<N extends NodeType = NodeType> = Readonly<{
+    kind: N["kind"];
+    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["kind"];
+    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["kind"];
+    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["kind"];
+    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.
+ *
+ * Note: Batch operations (`bulkCreate`, `bulkInsert`, `bulkUpsert`) skip
+ * per-item operation hooks for throughput. Query hooks still fire normally.
+ *
+ * @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;
+    /** Query default behaviors. */
+    queryDefaults?: Readonly<{
+        /** Default traversal ontology expansion mode (default: "inverse"). */
+        traversalExpansion?: TraversalExpansion;
+    }>;
+}>;
+/**
+ * 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>;
+    /** Get multiple nodes by ID, preserving input order (undefined for missing) */
+    getByIds: (ids: readonly NodeId<N>[], options?: QueryOptions) => Promise<readonly (Node<N> | undefined)[]>;
     /** Update a node */
     update: (id: NodeId<N>, props: Partial<z.input<N["schema"]>>, options?: Readonly<{
         validTo?: string;
@@ -629,14 +813,18 @@ type NodeCollection<N extends NodeType> = Readonly<{
     /**
      * Find nodes matching criteria.
      *
+     * Supports predicate filtering via the `where` option for SQL-level filtering.
      * For simple queries. Use store.query() for complex traversals.
      */
     find: (options?: Readonly<{
+        where?: (accessor: NodeAccessor<N>) => Predicate;
         limit?: number;
         offset?: number;
+        temporalMode?: TemporalMode;
+        asOf?: string;
     }>) => Promise<Node<N>[]>;
     /** Count nodes matching criteria */
-    count: () => Promise<number>;
+    count: (options?: QueryOptions) => Promise<number>;
     /**
      * Create or update a node.
      *
@@ -651,6 +839,7 @@ type NodeCollection<N extends NodeType> = Readonly<{
      * Create multiple nodes in a batch.
      *
      * More efficient than calling create() multiple times.
+     * Use `bulkInsert` for the dedicated fast path that skips returning results.
      */
     bulkCreate: (items: readonly Readonly<{
         props: z.input<N["schema"]>;
@@ -670,10 +859,24 @@ type NodeCollection<N extends NodeType> = Readonly<{
         validFrom?: string;
         validTo?: string;
     }>[]) => Promise<Node<N>[]>;
+    /**
+     * Insert multiple nodes without returning results.
+     *
+     * This is the dedicated fast path for bulk inserts. Unlike `bulkCreate`
+     * with `returnResults: false`, the intent is unambiguous: no results
+     * are returned and the operation is wrapped in a transaction.
+     */
+    bulkInsert: (items: readonly Readonly<{
+        props: z.input<N["schema"]>;
+        id?: string;
+        validFrom?: string;
+        validTo?: string;
+    }>[]) => Promise<void>;
     /**
      * Delete multiple nodes by ID.
      *
-     * Silently ignores IDs that don't exist.
+     * Atomic when the backend supports transactions. Silently ignores IDs
+     * that don't exist.
      */
     bulkDelete: (ids: readonly NodeId<N>[]) => Promise<void>;
 }>;
@@ -697,7 +900,7 @@ type NodeRef = Readonly<{
  * allowed node kinds defined in the edge registration.
  */
 type TypedNodeRef<N extends NodeType> = Node<N> | Readonly<{
-    kind: N["name"];
+    kind: N["kind"];
     id: string;
 }>;
 /**
@@ -750,6 +953,8 @@ type EdgeCollection<E extends AnyEdgeType, From extends NodeType = NodeType, To
     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>;
+    /** Get multiple edges by ID, preserving input order (undefined for missing) */
+    getByIds: (ids: readonly string[], options?: QueryOptions) => Promise<readonly (Edge<E> | undefined)[]>;
     /** Update an edge's properties */
     update: (id: string, props: Partial<z.input<E["schema"]>>, options?: Readonly<{
         validTo?: string;
@@ -770,22 +975,27 @@ type EdgeCollection<E extends AnyEdgeType, From extends NodeType = NodeType, To
      * Consider using soft delete (`delete()`) for most use cases.
      */
     hardDelete: (id: string) => Promise<void>;
-    /** Find edges matching criteria */
+    /** Find edges matching endpoint and pagination criteria */
     find: (options?: Readonly<{
         from?: TypedNodeRef<From>;
         to?: TypedNodeRef<To>;
         limit?: number;
         offset?: number;
+        temporalMode?: TemporalMode;
+        asOf?: string;
     }>) => Promise<Edge<E>[]>;
     /** Count edges matching criteria */
     count: (options?: Readonly<{
         from?: TypedNodeRef<From>;
         to?: TypedNodeRef<To>;
+        temporalMode?: TemporalMode;
+        asOf?: string;
     }>) => Promise<number>;
     /**
      * Create multiple edges in a batch.
      *
      * More efficient than calling create() multiple times.
+     * Use `bulkInsert` for the dedicated fast path that skips returning results.
      */
     bulkCreate: (items: readonly Readonly<{
         from: TypedNodeRef<From>;
@@ -793,463 +1003,83 @@ type EdgeCollection<E extends AnyEdgeType, From extends NodeType = NodeType, 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;
+        validTo?: string;
+    }>[]) => Promise<Edge<E>[]>;
+    /**
+     * Create or update multiple edges in a batch.
+     *
+     * For each item, if an edge with the given ID exists, updates it.
+     * Otherwise, creates a new edge with that ID.
+     */
+    bulkUpsert: (items: readonly Readonly<{
+        id: string;
+        from: TypedNodeRef<From>;
+        to: TypedNodeRef<To>;
+        props?: z.input<E["schema"]>;
+        validFrom?: string;
+        validTo?: string;
+    }>[]) => Promise<Edge<E>[]>;
+    /**
+     * Insert multiple edges without returning results.
+     *
+     * This is the dedicated fast path for bulk inserts. Unlike `bulkCreate`
+     * with `returnResults: false`, the intent is unambiguous: no results
+     * are returned and the operation is wrapped in a transaction.
+     */
+    bulkInsert: (items: readonly Readonly<{
+        from: TypedNodeRef<From>;
+        to: TypedNodeRef<To>;
+        props?: z.input<E["schema"]>;
+        id?: string;
+        validFrom?: string;
+        validTo?: string;
+    }>[]) => Promise<void>;
+    /**
+     * Delete multiple edges by ID.
+     *
+     * Atomic when the backend supports transactions. Silently ignores IDs
+     * that don't exist.
+     */
+    bulkDelete: (ids: readonly string[]) => Promise<void>;
 }>;
 /**
- * Options for streaming results.
+ * Extract the union of 'from' node types from an EdgeRegistration.
  */
-type StreamOptions = Readonly<{
-    /** Number of items to fetch per batch (default: 1000) */
-    batchSize?: number;
-}>;
+type EdgeFromTypes<R extends EdgeRegistration> = R["from"] extends readonly (infer N)[] ? N : never;
 /**
- * Configuration for the query builder.
+ * Extract the union of 'to' node types from an EdgeRegistration.
  */
-type QueryBuilderConfig = Readonly<{
-    graphId: string;
-    registry: KindRegistry;
-    schemaIntrospector: SchemaIntrospector;
-    backend?: GraphBackend;
-    dialect?: SqlDialect;
-    /** SQL schema configuration for custom table names. */
-    schema?: SqlSchema;
-}>;
+type EdgeToTypes<R extends EdgeRegistration> = R["to"] extends readonly (infer N)[] ? N : never;
 /**
- * Internal state of the query builder.
+ * Create a type-safe EdgeCollection from an EdgeRegistration.
+ * Extracts the edge type and from/to node types automatically.
  */
-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;
-}>;
+type TypedEdgeCollection<R extends EdgeRegistration> = EdgeCollection<R["type"], EdgeFromTypes<R> extends NodeType ? EdgeFromTypes<R> : NodeType, EdgeToTypes<R> extends NodeType ? EdgeToTypes<R> : NodeType>;
 /**
- * Options for creating a query builder.
+ * 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 CreateQueryBuilderOptions = Readonly<{
-    /** Backend for query execution */
-    backend?: GraphBackend;
-    /** SQL dialect for compilation */
-    dialect?: SqlDialect;
-    /** SQL schema configuration for custom table names */
-    schema?: SqlSchema;
+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]>;
+    };
 }>;
 
 /**
@@ -1281,6 +1111,16 @@ declare class ExecutableAggregateQuery<G extends GraphDef, Aliases extends Alias
      * Offsets the results.
      */
     offset(n: number): ExecutableAggregateQuery<G, Aliases, R>;
+    /**
+     * Compiles the query and returns the SQL text and parameters.
+     *
+     * Requires a backend to be configured (the backend determines the SQL dialect).
+     * Use this for debugging, logging, or running the query with a custom executor.
+     */
+    toSQL(): Readonly<{
+        sql: string;
+        params: readonly unknown[];
+    }>;
     /**
      * Compiles the query to a Drizzle SQL object.
      */
@@ -1293,6 +1133,52 @@ declare class ExecutableAggregateQuery<G extends GraphDef, Aliases extends Alias
     execute(): Promise<readonly AggregateResult<R>[]>;
 }
 
+type PreparedQueryConfig<R> = Readonly<{
+    ast: QueryAst;
+    unoptimizedAst: QueryAst;
+    sqlText: string | undefined;
+    sqlParams: readonly unknown[] | undefined;
+    unoptimizedSqlText: string | undefined;
+    unoptimizedSqlParams: readonly unknown[] | undefined;
+    backend: GraphBackend;
+    dialect: SqlDialect;
+    graphId: string;
+    compileOptions: CompileQueryOptions;
+    state: QueryBuilderState;
+    selectiveFields: readonly SelectiveField[] | undefined;
+    selectFn: (context: SelectContext<AliasMap, EdgeAliasMap>) => R;
+    schemaIntrospector: SchemaIntrospector;
+}>;
+/**
+ * A pre-compiled, parameterized query.
+ *
+ * @example
+ * ```typescript
+ * const prepared = store.query()
+ *   .from("Person", "p")
+ *   .whereNode("p", (p) => p.name.eq(param("name")))
+ *   .select((ctx) => ctx.p)
+ *   .prepare();
+ *
+ * // Execute with different bindings
+ * const alice = await prepared.execute({ name: "Alice" });
+ * const bob = await prepared.execute({ name: "Bob" });
+ * ```
+ */
+declare class PreparedQuery<R> {
+    #private;
+    constructor(config: PreparedQueryConfig<R>);
+    /** The set of parameter names required by this prepared query. */
+    get parameterNames(): ReadonlySet<string>;
+    /**
+     * Executes the prepared query with the given parameter bindings.
+     *
+     * @param bindings - A record mapping parameter names to their values
+     * @returns The query results
+     */
+    execute(bindings?: Readonly<Record<string, unknown>>): Promise<readonly R[]>;
+}
+
 /**
  * UnionableQuery - A query formed by combining multiple queries with set operations.
  */
@@ -1348,6 +1234,16 @@ declare class UnionableQuery<G extends GraphDef, R> {
      * Builds the set operation AST.
      */
     toAst(): SetOperation;
+    /**
+     * Compiles the query and returns the SQL text and parameters.
+     *
+     * Requires a backend to be configured (the backend determines the SQL dialect).
+     * Use this for debugging, logging, or running the query with a custom executor.
+     */
+    toSQL(): Readonly<{
+        sql: string;
+        params: readonly unknown[];
+    }>;
     /**
      * Compiles the set operation to SQL.
      */
@@ -1365,9 +1261,9 @@ declare class UnionableQuery<G extends GraphDef, R> {
 /**
  * A query that can be executed.
  */
-declare class ExecutableQuery<G extends GraphDef, Aliases extends AliasMap, EdgeAliases extends EdgeAliasMap = {}, R = unknown> {
+declare class ExecutableQuery<G extends GraphDef, Aliases extends AliasMap, EdgeAliases extends EdgeAliasMap = {}, RecursiveAliases extends RecursiveAliasMap = {}, R = unknown> {
     #private;
-    constructor(config: QueryBuilderConfig, state: QueryBuilderState, selectFunction: (context: SelectContext<Aliases, EdgeAliases>) => R);
+    constructor(config: QueryBuilderConfig, state: QueryBuilderState, selectFunction: (context: SelectContext<Aliases, EdgeAliases, RecursiveAliases>) => R);
     /**
      * Builds the query AST.
      */
@@ -1375,15 +1271,15 @@ declare class ExecutableQuery<G extends GraphDef, Aliases extends AliasMap, Edge
     /**
      * Orders results.
      */
-    orderBy<A extends keyof Aliases & string>(alias: A, field: string, direction?: SortDirection): ExecutableQuery<G, Aliases, EdgeAliases, R>;
+    orderBy<A extends keyof Aliases & string>(alias: A, field: string, direction?: SortDirection): ExecutableQuery<G, Aliases, EdgeAliases, RecursiveAliases, R>;
     /**
      * Limits the number of results.
      */
-    limit(n: number): ExecutableQuery<G, Aliases, EdgeAliases, R>;
+    limit(n: number): ExecutableQuery<G, Aliases, EdgeAliases, RecursiveAliases, R>;
     /**
      * Offsets the results.
      */
-    offset(n: number): ExecutableQuery<G, Aliases, EdgeAliases, R>;
+    offset(n: number): ExecutableQuery<G, Aliases, EdgeAliases, RecursiveAliases, R>;
     /**
      * Applies a query fragment to transform this executable query.
      *
@@ -1404,23 +1300,33 @@ declare class ExecutableQuery<G extends GraphDef, Aliases extends AliasMap, Edge
      * @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>;
+    pipe<NewR = R>(fragment: (query: ExecutableQuery<G, Aliases, EdgeAliases, RecursiveAliases, R>) => ExecutableQuery<G, Aliases, EdgeAliases, RecursiveAliases, NewR>): ExecutableQuery<G, Aliases, EdgeAliases, RecursiveAliases, NewR>;
     /**
      * Combines this query with another using UNION (removes duplicates).
      */
-    union(other: ExecutableQuery<G, any, any, R>): UnionableQuery<G, R>;
+    union(other: ExecutableQuery<G, any, 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>;
+    unionAll(other: ExecutableQuery<G, any, any, any, R>): UnionableQuery<G, R>;
     /**
      * Combines this query with another using INTERSECT.
      */
-    intersect(other: ExecutableQuery<G, any, any, R>): UnionableQuery<G, R>;
+    intersect(other: ExecutableQuery<G, any, any, any, R>): UnionableQuery<G, R>;
     /**
      * Combines this query with another using EXCEPT.
      */
-    except(other: ExecutableQuery<G, any, any, R>): UnionableQuery<G, R>;
+    except(other: ExecutableQuery<G, any, any, any, R>): UnionableQuery<G, R>;
+    /**
+     * Compiles the query and returns the SQL text and parameters.
+     *
+     * Requires a backend to be configured (the backend determines the SQL dialect).
+     * Use this for debugging, logging, or running the query with a custom executor.
+     */
+    toSQL(): Readonly<{
+        sql: string;
+        params: readonly unknown[];
+    }>;
     /**
      * Compiles the query to a Drizzle SQL object.
      *
@@ -1428,6 +1334,30 @@ declare class ExecutableQuery<G extends GraphDef, Aliases extends AliasMap, Edge
      * with db.all(), db.get(), etc.
      */
     compile(): SQL;
+    /**
+     * Creates a prepared (pre-compiled) query that can be executed
+     * multiple times with different parameter bindings.
+     *
+     * Use `param("name")` in predicates to create parameterized slots,
+     * then pass values via `prepared.execute({ name: "value" })`.
+     *
+     * @example
+     * ```typescript
+     * import { param } from "@nicia-ai/typegraph";
+     *
+     * const prepared = store.query()
+     *   .from("Person", "p")
+     *   .whereNode("p", (p) => p.name.eq(param("name")))
+     *   .select((ctx) => ctx.p)
+     *   .prepare();
+     *
+     * const alice = await prepared.execute({ name: "Alice" });
+     * const bob = await prepared.execute({ name: "Bob" });
+     * ```
+     *
+     * @throws Error if no backend is configured
+     */
+    prepare(): PreparedQuery<R>;
     /**
      * Executes the query and returns typed results.
      *
@@ -1473,8 +1403,10 @@ interface VariableLengthState {
     enabled: boolean;
     minDepth: number;
     maxDepth: number;
-    collectPath: boolean;
+    cyclePolicy: RecursiveCyclePolicy;
+    pathEnabled: boolean;
     pathAlias?: string;
+    depthEnabled: boolean;
     depthAlias?: string;
 }
 /**
@@ -1483,41 +1415,25 @@ interface VariableLengthState {
  * 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> {
+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, DC extends boolean | string = false, PC extends boolean | string = false, RecAliases extends RecursiveAliasMap = {}> {
     #private;
-    constructor(config: QueryBuilderConfig, state: QueryBuilderState, edgeKinds: readonly string[], edgeAlias: EA, direction: Dir, fromAlias: string, optional?: Optional, variableLength?: VariableLengthState, pendingEdgePredicates?: readonly NodePredicate[]);
+    constructor(config: QueryBuilderConfig, state: QueryBuilderState, edgeKinds: readonly string[], edgeAlias: EA, direction: Dir, fromAlias: string, inverseEdgeKinds?: readonly 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")
+     * By default, traverses unlimited depth with cycle prevention.
      */
-    withDepth(alias?: string): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, Dir, Optional>;
+    recursive<const O extends RecursiveTraversalOptions = Record<string, never>>(options?: O): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, Dir, Optional, O extends {
+        depth: infer D extends boolean | string;
+    } ? D : DC, O extends {
+        path: infer P extends boolean | string;
+    } ? P : PC, RecAliases>;
     /**
      * 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>;
+    whereEdge(alias: EA, predicateFunction: (edge: EdgeAccessor<G["edges"][EK]["type"]>) => Predicate): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, Dir, Optional, DC, PC, RecAliases>;
     /**
      * Specifies the target node kind.
      *
@@ -1530,10 +1446,10 @@ declare class TraversalBuilder<G extends GraphDef, Aliases extends AliasMap, Edg
      */
     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>>>;
+    }): QueryBuilder<G, Aliases & Record<A, NodeAlias<G["nodes"][K]["type"], Optional>>, EdgeAliases & Record<EA, EdgeAlias<G["edges"][EK]["type"], Optional>>, RecAliases & BuildRecursiveAliases<DC, PC, A>>;
     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<G, Aliases & Record<A, NodeAlias<NodeType, Optional>>, EdgeAliases & Record<EA, EdgeAlias<G["edges"][EK]["type"], Optional>>, RecAliases & BuildRecursiveAliases<DC, PC, A>>;
 }
 
 /**
@@ -1548,7 +1464,7 @@ declare class TraversalBuilder<G extends GraphDef, Aliases extends AliasMap, Edg
  * - 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 = {}> {
+declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = {}, EdgeAliases extends EdgeAliasMap = {}, RecursiveAliases extends RecursiveAliasMap = {}> {
     #private;
     constructor(config: QueryBuilderConfig, state: QueryBuilderState);
     /**
@@ -1559,35 +1475,35 @@ declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = {}, Ed
      */
     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>;
+    }): QueryBuilder<G, Aliases & Record<A, NodeAlias<G["nodes"][K]["type"]>>, EdgeAliases, RecursiveAliases>;
     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>;
+    }): QueryBuilder<G, Aliases & Record<A, NodeAlias>, EdgeAliases, RecursiveAliases>;
     /**
      * 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>;
+    whereNode<A extends keyof Aliases & string>(alias: A, predicateFunction: (n: NodeAccessor<Aliases[A]["type"]>) => Predicate): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>;
     /**
      * 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>;
+    whereEdge<EA extends keyof EdgeAliases & string>(alias: EA, predicateFunction: (edge: EdgeAccessor<EdgeAliases[EA]["type"]>) => Predicate): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>;
     /**
      * 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.expand - Ontology expansion mode for implying/inverse edges
      * @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;
+        expand?: TraversalExpansion;
         from?: keyof Aliases & string;
-    }): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA>;
+    }): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, "out", false, false, false, RecursiveAliases>;
     /**
      * Traverses an edge to another node (incoming direction).
      *
@@ -1595,14 +1511,14 @@ declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = {}, Ed
      * 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.expand - Ontology expansion mode for implying/inverse edges
      * @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;
+        expand?: TraversalExpansion;
         from?: keyof Aliases & string;
-    }): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, "in">;
+    }): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, "in", false, false, false, RecursiveAliases>;
     /**
      * Optionally traverses an edge to another node (LEFT JOIN semantics).
      * If no matching edge/node exists, the result will include null values.
@@ -1611,42 +1527,42 @@ declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = {}, Ed
      * 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.expand - Ontology expansion mode for implying/inverse edges
      * @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;
+        expand?: TraversalExpansion;
         from?: keyof Aliases & string;
-    }): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, "out", true>;
+    }): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, "out", true, false, false, RecursiveAliases>;
     optionalTraverse<EK extends keyof G["edges"] & string, EA extends string>(edgeKind: EK, edgeAlias: EA, options: {
         direction: "in";
-        includeImplyingEdges?: boolean;
+        expand?: TraversalExpansion;
         from?: keyof Aliases & string;
-    }): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, "in", true>;
+    }): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, "in", true, false, false, RecursiveAliases>;
     /**
      * Selects fields to return.
      */
-    select<R>(selectFunction: (context: SelectContext<Aliases, EdgeAliases>) => R): ExecutableQuery<G, Aliases, EdgeAliases, R>;
+    select<R>(selectFunction: (context: SelectContext<Aliases, EdgeAliases, RecursiveAliases>) => R): ExecutableQuery<G, Aliases, EdgeAliases, RecursiveAliases, 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>;
+    aggregate<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>;
+    orderBy<A extends keyof Aliases & string>(alias: A, field: string, direction?: SortDirection): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>;
     /**
      * Limits the number of results.
      */
-    limit(n: number): QueryBuilder<G, Aliases, EdgeAliases>;
+    limit(n: number): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>;
     /**
      * Offsets the results.
      */
-    offset(n: number): QueryBuilder<G, Aliases, EdgeAliases>;
+    offset(n: number): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>;
     /**
      * Sets temporal mode.
      *
@@ -1654,7 +1570,7 @@ declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = {}, Ed
      * @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>;
+    temporal(mode: TemporalMode, asOf?: string): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>;
     /**
      * Groups results by the specified field.
      * Use with aggregate functions like COUNT, SUM, AVG in select().
@@ -1662,21 +1578,21 @@ declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = {}, Ed
      * @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>;
+    groupBy<A extends keyof Aliases & string>(alias: A, field: string): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>;
     /**
      * 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>;
+    groupByNode<A extends keyof Aliases & string>(alias: A): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>;
     /**
      * 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>;
+    having(predicate: PredicateExpression): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>;
     /**
      * Applies a query fragment to transform this builder.
      *
@@ -1702,336 +1618,9 @@ declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = {}, Ed
      * @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>;
+    pipe<OutAliases extends AliasMap, OutEdgeAliases extends EdgeAliasMap = EdgeAliases, OutRecAliases extends RecursiveAliasMap = RecursiveAliases>(fragment: (builder: QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>) => QueryBuilder<G, OutAliases, OutEdgeAliases, OutRecAliases>): QueryBuilder<G, OutAliases, OutEdgeAliases, OutRecAliases>;
 }
 
-/**
- * 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.
  *
@@ -2221,9 +1810,11 @@ declare function createStore<G extends GraphDef>(graph: G, backend: GraphBackend
  *   console.log("Schema initialized at version", result.version);
  * } else if (result.status === "migrated") {
  *   console.log(`Migrated from v${result.fromVersion} to v${result.toVersion}`);
+ * } else if (result.status === "pending") {
+ *   console.log(`Safe changes pending at version ${result.version}`);
  * }
  * ```
  */
 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 };
+export { notExists as $, type AliasMap as A, type TransactionContext as B, type CreateQueryBuilderOptions as C, type TypedEdgeCollection as D, type EdgeAliasMap as E, type FieldAccessor as F, type TypedNodeRef as G, type HookContext as H, type UpdateEdgeInput as I, type UpdateNodeInput as J, createStore as K, createStoreWithSchema as L, embedding as M, type Node as N, type OperationHookContext as O, type PaginateOptions as P, QueryBuilder as Q, type RecursiveTraversalOptions as R, Store as S, TraversalBuilder as T, UnionableQuery as U, exists as V, fieldRef as W, getEmbeddingDimensions as X, inSubquery as Y, isEmbeddingSchema as Z, isParameterRef as _, type AggregateResult as a, notInSubquery as a0, param as a1, type CreateEdgeInput as b, type CreateNodeInput as c, type Edge as d, type EdgeAccessor as e, type EdgeCollection as f, type EmbeddingSchema as g, type EmbeddingValue as h, ExecutableAggregateQuery as i, ExecutableQuery as j, type NodeAccessor as k, type NodeAlias as l, type NodeCollection as m, type NodeRef as n, type PaginatedResult as o, type Predicate as p, PreparedQuery as q, type PropsAccessor as r, type QueryHookContext as s, type QueryOptions as t, type SelectContext as u, type SelectableEdge as v, type SelectableNode as w, type StoreHooks as x, type StoreOptions as y, type StreamOptions as z };