Optimize traversal/query execution and add performance measurement guardrails

[pdlug]

Re-architects the SQL compiler and Drizzle backend into modular, dialect-aware layers while delivering performance improvements across query compilation, execution, traversal, and ingestion paths. Simplifies and tightens the public API surface, adds prepared query support, and introduces benchmark regression guardrails in CI.

Breaking API Changes

• selectAggregate(...) renamed to aggregate(...)
• includeImplyingEdges replaced with expand: "none" | "implying" | "inverse" | "all" (default: "inverse")
• Recursive traversal methods (.maxHops(), .minHops(), .collectPath(), .withDepth()) consolidated into recursive({ minHops, maxHops, cyclePolicy, path, depth })
• Cycle behavior now explicit via cyclePolicy: "prevent" | "allow" (default: "prevent")
• Unbounded recursion capped at MAX_RECURSIVE_DEPTH = 100; explicit maxHops validated up to MAX_EXPLICIT_RECURSIVE_DEPTH = 1000
• EdgeTypeNames / NodeTypeNames renamed to EdgeKinds / NodeKinds; getEdgeTypeNames() / getNodeTypeNames() renamed to getEdgeKinds() / getNodeKinds()
• Store class exported as type-only (prevents new Store(), preserves Store<G> annotations)
• StoreConfig replaced by StoreOptions (adds queryDefaults.traversalExpansion)

Public API Surface Reduction

Schema management extracted to new @nicia-ai/typegraph/schema sub-export:

• Moved: serializeSchema, deserializeSchema, computeSchemaHash, initializeSchema, ensureSchema, migrateSchema, computeSchemaDiff, getMigrationActions, isBackwardsCompatible, all serialized types, and validation utilities

Removed from main entry point:

• Compiler internals: QueryAst, SetOperation, ValueType, VariableLengthSpec, logical plan types, predicate/temporal/recursive compiler functions
• getDialect, DialectAdapter (kept SqlDialect as type-only)
• Profiler internals: extractPropertyAccesses, ProfileCollector, keyToPath/pathToKey, generateRecommendations, getUnindexedFilters
• KindRegistry / buildKindRegistry
• Result utilities (ok/err/isOk/isErr/unwrap/unwrapOr)
• encodeDate / decodeDate
• Validation utilities (createValidationError, validateProps, wrapZodError)

New Features

Prepared Queries

• param(name) placeholders for scalar predicate positions
• .prepare() precompiles AST → SQL text once; prepared.execute(bindings) runs with zero recompilation
• Strict bindings validation (all declared params required, unknown bindings rejected)
• Falls back to AST recompilation when raw execution is unavailable

Collection API Additions

• getByIds(ids) on node/edge collections — batched SELECT ... WHERE id IN (...), preserves input order, returns undefined for missing IDs
• bulkInsert — void-returning fire-and-forget ingestion
• bulkCreate — multi-row INSERT ... RETURNING instead of per-item inserts
• bulkUpsert (edges) — batch getNodes lookup instead of N+1 sequential calls
• Node find({ where }) — delegates to query builder with full predicate support
• count() now accepts QueryOptions (temporal mode, asOf)

Store & Type Additions

• New hook types: StoreHooks, HookContext, OperationHookContext, QueryHookContext
• TypedEdgeCollection, TypedNodeRef type exports
• New error classes: CompilerInvariantError, DatabaseOperationError
• New Result combinators: flatMap, map, mapErr, orElse

Compiler Architecture

SQL compilation restructured into a three-stage pipeline:

Query AST → Logical Plan → Compiler Passes → SQL Emitter → Drizzle SQL

• plan/ — Intermediate representation with 9 plan node types (Scan, Filter, Join, Aggregate, Sort, Limit, VectorKnn, RecursiveExpand, SetOp); lowering functions for standard, recursive, and set-operation queries
• passes/ — Multi-pass optimization framework with temporal, recursive, and vector passes
• emitter/ — SQL generation from logical plans; plan-inspector.ts validates plan shape before emission; standard-builders.ts extracts CTE/projection/clause construction
• standard-pass-pipeline.ts — Orchestrates passes, predicate indexing, and column pruning

Compiler introduces predicate pre-indexing, column pruning, and compilation caching to reduce per-query overhead.

Backend Architecture

Backend refactored from monolithic operations.ts into concern-based modules with dialect-polymorphic strategy dispatch..

Benchmarks

Complete rewrite of @nicia-ai/typegraph-benchmarks — replaced tinybench with a custom measurement framework:

• Modular architecture: cli.ts, config.ts, backend.ts, measurements.ts, guardrails.ts, seed.ts
• Scenarios: forward/reverse/inverse traversals, multi-hop (2/3-hop), recursive (100/1000-hop), aggregates, cached vs prepared execution
• Regression guardrails with backend-specific threshold overrides for SQLite and PostgreSQL
• CI integration: new perf:check and perf:check:postgres steps in GitHub Actions

Testing

Expanded test coverage for existing public APIs and added extensive new tests for the new APIs and backend refactor

Documentation

New pages: Schema Evolution guide, Testing guide, Query Execution reference

Major expansions: Performance overview (+411 lines), recursive queries, predicates reference, schemas & stores, traversal docs

Updated for new APIs: aggregate(), traversal expand modes, recursive options, bulkInsert, bulkCreate, getByIds, node find({ where }), prepared queries