@nicia-ai/typegraph 0.22.0 → 0.23.0

package/dist/indexes/index.d.cts

@@ -1,12 +1,12 @@
-import { S as SqlDialect, A as AnyEdgeType, N as NodeType } from '../types-CQF88McG.cjs';
-import { E as EdgeIndex, T as TypeGraphIndex, N as NodeIndex, a as EdgeIndexConfig, b as NodeIndexConfig, I as IndexWhereExpression } from '../types-vgjar7Ch.cjs';
-export { c as EdgeIndexDirection, d as EdgeIndexWhereBuilder, e as IndexScope, f as IndexWhereFieldBuilder, g as IndexWhereInput, h as NodeIndexWhereBuilder, S as SystemColumnName } from '../types-vgjar7Ch.cjs';
+import { S as SqlDialect, A as AnyEdgeType, N as NodeType } from '../types-Qk2l3IkQ.cjs';
+import { E as EdgeIndex, T as TypeGraphIndex, N as NodeIndex, a as EdgeIndexConfig, b as NodeIndexConfig, I as IndexWhereExpression } from '../types-CQx4iW5Y.cjs';
+export { c as EdgeIndexDirection, d as EdgeIndexWhereBuilder, e as IndexScope, f as IndexWhereFieldBuilder, g as IndexWhereInput, h as NodeIndexWhereBuilder, S as SystemColumnName } from '../types-CQx4iW5Y.cjs';
 import { SQLWrapper } from 'drizzle-orm';
 import { IndexBuilder } from 'drizzle-orm/pg-core';
 import { IndexBuilder as IndexBuilder$1 } from 'drizzle-orm/sqlite-core';
-import { D as DeclaredIndex } from '../types-D23slCOA.cjs';
+import { D as DeclaredIndex } from '../types-yH4_p0XB.cjs';
 import 'zod';
-import '../ast-DogwbBqA.cjs';
+import '../ast-dgLhLOg0.cjs';
 
 type GenerateIndexDdlOptions = Readonly<{
     nodesTableName?: string | undefined;

package/dist/indexes/index.d.ts

@@ -1,12 +1,12 @@
-import { S as SqlDialect, A as AnyEdgeType, N as NodeType } from '../types-CQF88McG.js';
-import { E as EdgeIndex, T as TypeGraphIndex, N as NodeIndex, a as EdgeIndexConfig, b as NodeIndexConfig, I as IndexWhereExpression } from '../types-IMQCuser.js';
-export { c as EdgeIndexDirection, d as EdgeIndexWhereBuilder, e as IndexScope, f as IndexWhereFieldBuilder, g as IndexWhereInput, h as NodeIndexWhereBuilder, S as SystemColumnName } from '../types-IMQCuser.js';
+import { S as SqlDialect, A as AnyEdgeType, N as NodeType } from '../types-Qk2l3IkQ.js';
+import { E as EdgeIndex, T as TypeGraphIndex, N as NodeIndex, a as EdgeIndexConfig, b as NodeIndexConfig, I as IndexWhereExpression } from '../types-C-zfYDJB.js';
+export { c as EdgeIndexDirection, d as EdgeIndexWhereBuilder, e as IndexScope, f as IndexWhereFieldBuilder, g as IndexWhereInput, h as NodeIndexWhereBuilder, S as SystemColumnName } from '../types-C-zfYDJB.js';
 import { SQLWrapper } from 'drizzle-orm';
 import { IndexBuilder } from 'drizzle-orm/pg-core';
 import { IndexBuilder as IndexBuilder$1 } from 'drizzle-orm/sqlite-core';
-import { D as DeclaredIndex } from '../types-CglvhPKz.js';
+import { D as DeclaredIndex } from '../types-qYFZ9SqD.js';
 import 'zod';
-import '../ast-CSLbPIOC.js';
+import '../ast-C8S37w1A.js';
 
 type GenerateIndexDdlOptions = Readonly<{
     nodesTableName?: string | undefined;

package/dist/interchange/index.d.cts

@@ -1,9 +1,9 @@
 import { z } from 'zod';
-import { G as GraphDef } from '../manager-BPK-2PUI.cjs';
-import { aj as Store } from '../store-2QW2SIRk.cjs';
-import '../types-CQF88McG.cjs';
+import { G as GraphDef } from '../manager-Vkz28eAC.cjs';
+import { aj as Store } from '../store-CpvwTMxV.cjs';
+import '../types-Qk2l3IkQ.cjs';
 import 'drizzle-orm';
-import '../ast-DogwbBqA.cjs';
+import '../ast-dgLhLOg0.cjs';
 
 /**
  * Graph interchange format types.

package/dist/interchange/index.d.ts

@@ -1,9 +1,9 @@
 import { z } from 'zod';
-import { G as GraphDef } from '../manager-0jVZtiE8.js';
-import { aj as Store } from '../store-C0q13mtJ.js';
-import '../types-CQF88McG.js';
+import { G as GraphDef } from '../manager-nIhmttD-.js';
+import { aj as Store } from '../store-U3i2tUch.js';
+import '../types-Qk2l3IkQ.js';
 import 'drizzle-orm';
-import '../ast-CSLbPIOC.js';
+import '../ast-C8S37w1A.js';
 
 /**
  * Graph interchange format types.

package/dist/{manager-BPK-2PUI.d.cts → manager-Vkz28eAC.d.cts}

@@ -1,4 +1,4 @@
-import { r as NodeRegistration, f as EdgeRegistration, O as OntologyRelation, b as DeleteBehavior, T as TemporalMode, N as NodeType, A as AnyEdgeType, n as GraphDefaults, W as SerializedNodeDef, X as SerializedEdgeDef, $ as SerializedSchema, G as GraphBackend, a4 as SchemaVersionRow } from './types-CQF88McG.cjs';
+import { r as NodeRegistration, f as EdgeRegistration, O as OntologyRelation, b as DeleteBehavior, T as TemporalMode, N as NodeType, A as AnyEdgeType, n as GraphDefaults, W as SerializedNodeDef, X as SerializedEdgeDef, $ as SerializedSchema, G as GraphBackend, a4 as SchemaVersionRow } from './types-Qk2l3IkQ.cjs';
 
 /** Brand key for GraphDef */
 declare const GRAPH_DEF_BRAND: "__graphDef";

package/dist/{manager-0jVZtiE8.d.ts → manager-nIhmttD-.d.ts}

@@ -1,4 +1,4 @@
-import { r as NodeRegistration, f as EdgeRegistration, O as OntologyRelation, b as DeleteBehavior, T as TemporalMode, N as NodeType, A as AnyEdgeType, n as GraphDefaults, W as SerializedNodeDef, X as SerializedEdgeDef, $ as SerializedSchema, G as GraphBackend, a4 as SchemaVersionRow } from './types-CQF88McG.js';
+import { r as NodeRegistration, f as EdgeRegistration, O as OntologyRelation, b as DeleteBehavior, T as TemporalMode, N as NodeType, A as AnyEdgeType, n as GraphDefaults, W as SerializedNodeDef, X as SerializedEdgeDef, $ as SerializedSchema, G as GraphBackend, a4 as SchemaVersionRow } from './types-Qk2l3IkQ.js';
 
 /** Brand key for GraphDef */
 declare const GRAPH_DEF_BRAND: "__graphDef";

package/dist/profiler/index.d.cts

@@ -1,9 +1,9 @@
-import { G as GraphDef } from '../manager-BPK-2PUI.cjs';
-import { Q as QueryAst } from '../ast-DogwbBqA.cjs';
-import { aj as Store } from '../store-2QW2SIRk.cjs';
-import { P as ProfilerOptions, a as ProfileReport } from '../types-D23slCOA.cjs';
-export { D as DeclaredIndex, I as IndexRecommendation, b as ProfileSummary, c as PropertyAccessStats, d as PropertyPath, R as RecommendationPriority, U as UsageContext } from '../types-D23slCOA.cjs';
-import '../types-CQF88McG.cjs';
+import { G as GraphDef } from '../manager-Vkz28eAC.cjs';
+import { Q as QueryAst } from '../ast-dgLhLOg0.cjs';
+import { aj as Store } from '../store-CpvwTMxV.cjs';
+import { P as ProfilerOptions, a as ProfileReport } from '../types-yH4_p0XB.cjs';
+export { D as DeclaredIndex, I as IndexRecommendation, b as ProfileSummary, c as PropertyAccessStats, d as PropertyPath, R as RecommendationPriority, U as UsageContext } from '../types-yH4_p0XB.cjs';
+import '../types-Qk2l3IkQ.cjs';
 import 'drizzle-orm';
 import 'zod';
 

package/dist/profiler/index.d.ts

@@ -1,9 +1,9 @@
-import { G as GraphDef } from '../manager-0jVZtiE8.js';
-import { Q as QueryAst } from '../ast-CSLbPIOC.js';
-import { aj as Store } from '../store-C0q13mtJ.js';
-import { P as ProfilerOptions, a as ProfileReport } from '../types-CglvhPKz.js';
-export { D as DeclaredIndex, I as IndexRecommendation, b as ProfileSummary, c as PropertyAccessStats, d as PropertyPath, R as RecommendationPriority, U as UsageContext } from '../types-CglvhPKz.js';
-import '../types-CQF88McG.js';
+import { G as GraphDef } from '../manager-nIhmttD-.js';
+import { Q as QueryAst } from '../ast-C8S37w1A.js';
+import { aj as Store } from '../store-U3i2tUch.js';
+import { P as ProfilerOptions, a as ProfileReport } from '../types-qYFZ9SqD.js';
+export { D as DeclaredIndex, I as IndexRecommendation, b as ProfileSummary, c as PropertyAccessStats, d as PropertyPath, R as RecommendationPriority, U as UsageContext } from '../types-qYFZ9SqD.js';
+import '../types-Qk2l3IkQ.js';
 import 'drizzle-orm';
 import 'zod';
 

package/dist/schema/index.d.cts

@@ -1,7 +1,7 @@
-import { K as KindRegistry, G as GraphDef } from '../manager-BPK-2PUI.cjs';
-export { C as ChangeSeverity, h as ChangeType, j as EdgeChange, M as MigrationHookContext, k as NodeChange, O as OntologyChange, l as SchemaDiff, S as SchemaManagerOptions, d as SchemaValidationResult, m as computeSchemaDiff, n as ensureSchema, o as getActiveSchema, p as getMigrationActions, q as getSchemaChanges, r as initializeSchema, s as isBackwardsCompatible, t as isSchemaInitialized, u as migrateSchema, v as rollbackSchema } from '../manager-BPK-2PUI.cjs';
-import { W as SerializedNodeDef, X as SerializedEdgeDef, Y as SerializedMetaEdge, Z as SerializedOntologyRelation, _ as SerializedClosures, $ as SerializedSchema, a0 as SchemaHash } from '../types-CQF88McG.cjs';
-export { a1 as JsonSchema, a2 as SerializedOntology, a3 as SerializedUniqueConstraint } from '../types-CQF88McG.cjs';
+import { K as KindRegistry, G as GraphDef } from '../manager-Vkz28eAC.cjs';
+export { C as ChangeSeverity, h as ChangeType, j as EdgeChange, M as MigrationHookContext, k as NodeChange, O as OntologyChange, l as SchemaDiff, S as SchemaManagerOptions, d as SchemaValidationResult, m as computeSchemaDiff, n as ensureSchema, o as getActiveSchema, p as getMigrationActions, q as getSchemaChanges, r as initializeSchema, s as isBackwardsCompatible, t as isSchemaInitialized, u as migrateSchema, v as rollbackSchema } from '../manager-Vkz28eAC.cjs';
+import { W as SerializedNodeDef, X as SerializedEdgeDef, Y as SerializedMetaEdge, Z as SerializedOntologyRelation, _ as SerializedClosures, $ as SerializedSchema, a0 as SchemaHash } from '../types-Qk2l3IkQ.cjs';
+export { a1 as JsonSchema, a2 as SerializedOntology, a3 as SerializedUniqueConstraint } from '../types-Qk2l3IkQ.cjs';
 import { ZodType, ZodError } from 'zod';
 import { k as ValidationIssue, V as ValidationError } from '../index-DXkEXpNz.cjs';
 import 'drizzle-orm';

package/dist/schema/index.d.ts

@@ -1,7 +1,7 @@
-import { K as KindRegistry, G as GraphDef } from '../manager-0jVZtiE8.js';
-export { C as ChangeSeverity, h as ChangeType, j as EdgeChange, M as MigrationHookContext, k as NodeChange, O as OntologyChange, l as SchemaDiff, S as SchemaManagerOptions, d as SchemaValidationResult, m as computeSchemaDiff, n as ensureSchema, o as getActiveSchema, p as getMigrationActions, q as getSchemaChanges, r as initializeSchema, s as isBackwardsCompatible, t as isSchemaInitialized, u as migrateSchema, v as rollbackSchema } from '../manager-0jVZtiE8.js';
-import { W as SerializedNodeDef, X as SerializedEdgeDef, Y as SerializedMetaEdge, Z as SerializedOntologyRelation, _ as SerializedClosures, $ as SerializedSchema, a0 as SchemaHash } from '../types-CQF88McG.js';
-export { a1 as JsonSchema, a2 as SerializedOntology, a3 as SerializedUniqueConstraint } from '../types-CQF88McG.js';
+import { K as KindRegistry, G as GraphDef } from '../manager-nIhmttD-.js';
+export { C as ChangeSeverity, h as ChangeType, j as EdgeChange, M as MigrationHookContext, k as NodeChange, O as OntologyChange, l as SchemaDiff, S as SchemaManagerOptions, d as SchemaValidationResult, m as computeSchemaDiff, n as ensureSchema, o as getActiveSchema, p as getMigrationActions, q as getSchemaChanges, r as initializeSchema, s as isBackwardsCompatible, t as isSchemaInitialized, u as migrateSchema, v as rollbackSchema } from '../manager-nIhmttD-.js';
+import { W as SerializedNodeDef, X as SerializedEdgeDef, Y as SerializedMetaEdge, Z as SerializedOntologyRelation, _ as SerializedClosures, $ as SerializedSchema, a0 as SchemaHash } from '../types-Qk2l3IkQ.js';
+export { a1 as JsonSchema, a2 as SerializedOntology, a3 as SerializedUniqueConstraint } from '../types-Qk2l3IkQ.js';
 import { ZodType, ZodError } from 'zod';
 import { k as ValidationIssue, V as ValidationError } from '../index-DXkEXpNz.js';
 import 'drizzle-orm';

package/dist/{sqlite-D1rrwcir.d.cts → sqlite-D0aceIe0.d.cts}

@@ -1,5 +1,5 @@
 import * as drizzle_orm_sqlite_core from 'drizzle-orm/sqlite-core';
-import { T as TypeGraphIndex } from './types-vgjar7Ch.cjs';
+import { T as TypeGraphIndex } from './types-CQx4iW5Y.cjs';
 
 /**
  * Table name configuration.

package/dist/{sqlite-W3rmJMlc.d.ts → sqlite-SUxbZqfy.d.ts}

@@ -1,5 +1,5 @@
 import * as drizzle_orm_sqlite_core from 'drizzle-orm/sqlite-core';
-import { T as TypeGraphIndex } from './types-IMQCuser.js';
+import { T as TypeGraphIndex } from './types-C-zfYDJB.js';
 
 /**
  * Table name configuration.

package/dist/{store-C0q13mtJ.d.ts → store-CpvwTMxV.d.cts}

@@ -1,7 +1,7 @@
-import { S as SqlDialect, s as SqlSchema, m as FulltextStrategy, j as FulltextQueryMode, N as NodeType, G as GraphBackend, u as TransactionBackend, A as AnyEdgeType, T as TemporalMode, E as EdgeType, f as EdgeRegistration, d as EdgeId, p as NodeId, P as EdgeRow, Q as NodeRow, r as NodeRegistration, R as VectorMetric } from './types-CQF88McG.js';
-import { K as KindRegistry, G as GraphDef, E as EdgeKinds, N as NodeKinds, a as AllNodeTypes, S as SchemaManagerOptions, d as SchemaValidationResult } from './manager-0jVZtiE8.js';
+import { S as SqlDialect, s as SqlSchema, m as FulltextStrategy, j as FulltextQueryMode, N as NodeType, G as GraphBackend, u as TransactionBackend, A as AnyEdgeType, T as TemporalMode, E as EdgeType, f as EdgeRegistration, d as EdgeId, p as NodeId, P as EdgeRow, Q as NodeRow, r as NodeRegistration, R as VectorMetric } from './types-Qk2l3IkQ.cjs';
+import { K as KindRegistry, G as GraphDef, E as EdgeKinds, N as NodeKinds, a as AllNodeTypes, S as SchemaManagerOptions, d as SchemaValidationResult } from './manager-Vkz28eAC.cjs';
 import { z } from 'zod';
-import { V as ValueType, i as PredicateExpression, k as VectorMetricType, Q as QueryAst, J as JsonPointer, F as FieldRef, P as ParameterRef, c as JsonPointerInput, T as TraversalExpansion, l as Traversal, N as NodePredicate, m as ProjectedField, O as OrderSpec, G as GroupBySpec, H as HybridFusionOptions, o as RecursiveCyclePolicy, q as TraversalDirection$1, A as AggregateExpr, r as SelectiveField, s as ComposableQuery, t as SetOperationType, u as SetOperation, S as SortDirection } from './ast-CSLbPIOC.js';
+import { V as ValueType, i as PredicateExpression, k as VectorMetricType, Q as QueryAst, J as JsonPointer, F as FieldRef, P as ParameterRef, c as JsonPointerInput, T as TraversalExpansion, l as Traversal, N as NodePredicate, m as ProjectedField, O as OrderSpec, G as GroupBySpec, H as HybridFusionOptions, o as RecursiveCyclePolicy, q as TraversalDirection$1, A as AggregateExpr, r as SelectiveField, s as ComposableQuery, t as SetOperationType, u as SetOperation, S as SortDirection } from './ast-dgLhLOg0.cjs';
 import { SQL } from 'drizzle-orm';
 
 /**
@@ -2811,12 +2811,19 @@ declare class Store<G extends GraphDef> {
      */
     get search(): StoreSearch<G>;
     /**
-     * Executes multiple queries over a single connection with snapshot consistency.
+     * Executes multiple queries and returns a typed tuple of results.
      *
-     * Acquires one connection via an implicit transaction, executes each query
-     * sequentially on that connection, and returns a typed tuple of results.
-     * Each query preserves its own result type, projection, filtering,
-     * sorting, and pagination.
+     * Each query preserves its own result type, projection, filtering, sorting,
+     * and pagination.
+     *
+     * **Snapshot consistency is conditional.** When
+     * `backend.capabilities.transactions` is `true`, queries run sequentially
+     * on a single connection inside an implicit transaction and observe the
+     * same database snapshot. When transactions are unavailable
+     * (Cloudflare D1, `drizzle-orm/neon-http`), queries run sequentially over
+     * independent connections and may observe writes that landed between them.
+     * Branch on `backend.capabilities.transactions` if you need a guaranteed
+     * snapshot.
      *
      * Read-only — use `bulkCreate`, `bulkInsert`, etc. for write batching.
      *
@@ -2890,6 +2897,21 @@ declare class Store<G extends GraphDef> {
      *   );
      * });
      * ```
+     *
+     * **Backends without transactions.** When `backend.capabilities.transactions`
+     * is `false` (Cloudflare D1, `drizzle-orm/neon-http`), this method runs the
+     * callback against the same backend used outside `transaction()` — writes
+     * are applied as they happen and a thrown error does **not** roll back
+     * earlier writes inside the callback. Branch on
+     * `backend.capabilities.transactions` if you require atomicity:
+     *
+     * ```typescript
+     * if (backend.capabilities.transactions) {
+     *   await store.transaction(async (tx) => { ... });
+     * } else {
+     *   // sequential, non-atomic — handle partial-failure recovery yourself
+     * }
+     * ```
      */
     transaction<T>(fn: (tx: TransactionContext<G>) => Promise<T>): Promise<T>;
     /**
@@ -2902,6 +2924,34 @@ declare class Store<G extends GraphDef> {
      * The store is usable after clearing — new data can be created immediately.
      */
     clear(): Promise<void>;
+    /**
+     * Refreshes the backend's query-planner statistics.
+     *
+     * Call this once after a large initial import or bulk backfill. The
+     * planner uses table statistics to choose between TypeGraph's
+     * multi-column indexes; without fresh stats a forward traversal can
+     * pick a reverse index and run an order of magnitude slower than
+     * needed. Autovacuum / background statistics will catch up
+     * eventually, but calling this explicitly after a bulk load gives
+     * you correct latencies immediately.
+     *
+     * Implementations:
+     * - SQLite runs `ANALYZE`, populating `sqlite_stat1`
+     * - PostgreSQL runs `ANALYZE` on the TypeGraph-managed tables
+     *
+     * Costs a few tens of milliseconds at the sizes this library is
+     * designed for. Safe to call at any time.
+     *
+     * @example
+     * ```typescript
+     * // After a bulk import
+     * for (const batch of batches) {
+     *   await store.nodes.Document.bulkCreate(batch);
+     * }
+     * await store.refreshStatistics();
+     * ```
+     */
+    refreshStatistics(): Promise<void>;
     /**
      * Closes the store and releases underlying resources.
      *

package/dist/{store-2QW2SIRk.d.cts → store-U3i2tUch.d.ts}

@@ -1,7 +1,7 @@
-import { S as SqlDialect, s as SqlSchema, m as FulltextStrategy, j as FulltextQueryMode, N as NodeType, G as GraphBackend, u as TransactionBackend, A as AnyEdgeType, T as TemporalMode, E as EdgeType, f as EdgeRegistration, d as EdgeId, p as NodeId, P as EdgeRow, Q as NodeRow, r as NodeRegistration, R as VectorMetric } from './types-CQF88McG.cjs';
-import { K as KindRegistry, G as GraphDef, E as EdgeKinds, N as NodeKinds, a as AllNodeTypes, S as SchemaManagerOptions, d as SchemaValidationResult } from './manager-BPK-2PUI.cjs';
+import { S as SqlDialect, s as SqlSchema, m as FulltextStrategy, j as FulltextQueryMode, N as NodeType, G as GraphBackend, u as TransactionBackend, A as AnyEdgeType, T as TemporalMode, E as EdgeType, f as EdgeRegistration, d as EdgeId, p as NodeId, P as EdgeRow, Q as NodeRow, r as NodeRegistration, R as VectorMetric } from './types-Qk2l3IkQ.js';
+import { K as KindRegistry, G as GraphDef, E as EdgeKinds, N as NodeKinds, a as AllNodeTypes, S as SchemaManagerOptions, d as SchemaValidationResult } from './manager-nIhmttD-.js';
 import { z } from 'zod';
-import { V as ValueType, i as PredicateExpression, k as VectorMetricType, Q as QueryAst, J as JsonPointer, F as FieldRef, P as ParameterRef, c as JsonPointerInput, T as TraversalExpansion, l as Traversal, N as NodePredicate, m as ProjectedField, O as OrderSpec, G as GroupBySpec, H as HybridFusionOptions, o as RecursiveCyclePolicy, q as TraversalDirection$1, A as AggregateExpr, r as SelectiveField, s as ComposableQuery, t as SetOperationType, u as SetOperation, S as SortDirection } from './ast-DogwbBqA.cjs';
+import { V as ValueType, i as PredicateExpression, k as VectorMetricType, Q as QueryAst, J as JsonPointer, F as FieldRef, P as ParameterRef, c as JsonPointerInput, T as TraversalExpansion, l as Traversal, N as NodePredicate, m as ProjectedField, O as OrderSpec, G as GroupBySpec, H as HybridFusionOptions, o as RecursiveCyclePolicy, q as TraversalDirection$1, A as AggregateExpr, r as SelectiveField, s as ComposableQuery, t as SetOperationType, u as SetOperation, S as SortDirection } from './ast-C8S37w1A.js';
 import { SQL } from 'drizzle-orm';
 
 /**
@@ -2811,12 +2811,19 @@ declare class Store<G extends GraphDef> {
      */
     get search(): StoreSearch<G>;
     /**
-     * Executes multiple queries over a single connection with snapshot consistency.
+     * Executes multiple queries and returns a typed tuple of results.
      *
-     * Acquires one connection via an implicit transaction, executes each query
-     * sequentially on that connection, and returns a typed tuple of results.
-     * Each query preserves its own result type, projection, filtering,
-     * sorting, and pagination.
+     * Each query preserves its own result type, projection, filtering, sorting,
+     * and pagination.
+     *
+     * **Snapshot consistency is conditional.** When
+     * `backend.capabilities.transactions` is `true`, queries run sequentially
+     * on a single connection inside an implicit transaction and observe the
+     * same database snapshot. When transactions are unavailable
+     * (Cloudflare D1, `drizzle-orm/neon-http`), queries run sequentially over
+     * independent connections and may observe writes that landed between them.
+     * Branch on `backend.capabilities.transactions` if you need a guaranteed
+     * snapshot.
      *
      * Read-only — use `bulkCreate`, `bulkInsert`, etc. for write batching.
      *
@@ -2890,6 +2897,21 @@ declare class Store<G extends GraphDef> {
      *   );
      * });
      * ```
+     *
+     * **Backends without transactions.** When `backend.capabilities.transactions`
+     * is `false` (Cloudflare D1, `drizzle-orm/neon-http`), this method runs the
+     * callback against the same backend used outside `transaction()` — writes
+     * are applied as they happen and a thrown error does **not** roll back
+     * earlier writes inside the callback. Branch on
+     * `backend.capabilities.transactions` if you require atomicity:
+     *
+     * ```typescript
+     * if (backend.capabilities.transactions) {
+     *   await store.transaction(async (tx) => { ... });
+     * } else {
+     *   // sequential, non-atomic — handle partial-failure recovery yourself
+     * }
+     * ```
      */
     transaction<T>(fn: (tx: TransactionContext<G>) => Promise<T>): Promise<T>;
     /**
@@ -2902,6 +2924,34 @@ declare class Store<G extends GraphDef> {
      * The store is usable after clearing — new data can be created immediately.
      */
     clear(): Promise<void>;
+    /**
+     * Refreshes the backend's query-planner statistics.
+     *
+     * Call this once after a large initial import or bulk backfill. The
+     * planner uses table statistics to choose between TypeGraph's
+     * multi-column indexes; without fresh stats a forward traversal can
+     * pick a reverse index and run an order of magnitude slower than
+     * needed. Autovacuum / background statistics will catch up
+     * eventually, but calling this explicitly after a bulk load gives
+     * you correct latencies immediately.
+     *
+     * Implementations:
+     * - SQLite runs `ANALYZE`, populating `sqlite_stat1`
+     * - PostgreSQL runs `ANALYZE` on the TypeGraph-managed tables
+     *
+     * Costs a few tens of milliseconds at the sizes this library is
+     * designed for. Safe to call at any time.
+     *
+     * @example
+     * ```typescript
+     * // After a bulk import
+     * for (const batch of batches) {
+     *   await store.nodes.Document.bulkCreate(batch);
+     * }
+     * await store.refreshStatistics();
+     * ```
+     */
+    refreshStatistics(): Promise<void>;
     /**
      * Closes the store and releases underlying resources.
      *

package/dist/{types-IMQCuser.d.ts → types-C-zfYDJB.d.ts}

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { A as AnyEdgeType, E as EdgeType, N as NodeType } from './types-CQF88McG.js';
-import { J as JsonPointer, V as ValueType, b as JsonPointerFor, f as JsonPointerSegmentsFor } from './ast-CSLbPIOC.js';
+import { A as AnyEdgeType, E as EdgeType, N as NodeType } from './types-Qk2l3IkQ.js';
+import { J as JsonPointer, V as ValueType, b as JsonPointerFor, f as JsonPointerSegmentsFor } from './ast-C8S37w1A.js';
 
 type IndexScope = 
 /**

package/dist/{types-vgjar7Ch.d.cts → types-CQx4iW5Y.d.cts}

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { A as AnyEdgeType, E as EdgeType, N as NodeType } from './types-CQF88McG.cjs';
-import { J as JsonPointer, V as ValueType, b as JsonPointerFor, f as JsonPointerSegmentsFor } from './ast-DogwbBqA.cjs';
+import { A as AnyEdgeType, E as EdgeType, N as NodeType } from './types-Qk2l3IkQ.cjs';
+import { J as JsonPointer, V as ValueType, b as JsonPointerFor, f as JsonPointerSegmentsFor } from './ast-dgLhLOg0.cjs';
 
 type IndexScope = 
 /**

package/dist/{types-CQF88McG.d.ts → types-Qk2l3IkQ.d.cts}

@@ -970,7 +970,7 @@ type TransactionOptions = Readonly<{
 /**
  * Transaction backend - a backend scoped to a transaction.
  */
-type TransactionBackend = Omit<GraphBackend, "transaction" | "close">;
+type TransactionBackend = Omit<GraphBackend, "transaction" | "close" | "refreshStatistics">;
 /**
  * The GraphBackend interface abstracts database operations.
  *
@@ -1060,6 +1060,25 @@ type GraphBackend = Readonly<{
      * hit this path.
      */
     bootstrapTables?: () => Promise<void>;
+    /**
+     * Refreshes the backend's query-planner statistics.
+     *
+     * Call this once after a large initial import or bulk backfill. Without
+     * up-to-date statistics, the planner can pick suboptimal execution plans
+     * — on PostgreSQL this is the difference between a 0.5ms and a 5ms
+     * forward traversal; on SQLite it's the difference between 0.9ms and
+     * 23ms fulltext search. Autovacuum / background statistics collection
+     * will catch up eventually, but calling this explicitly after a bulk
+     * load gives you correct latencies immediately.
+     *
+     * Implementations:
+     * - SQLite runs `ANALYZE`, which populates `sqlite_stat1`
+     * - PostgreSQL runs `ANALYZE` on the TypeGraph-managed tables
+     *
+     * Safe to call at any time; costs a few tens of milliseconds on the
+     * sizes this library is designed for.
+     */
+    refreshStatistics: () => Promise<void>;
     execute: <T>(query: SQL) => Promise<readonly T[]>;
     /** Execute pre-compiled SQL text with bound parameters. Available on sync SQLite and pg backends. */
     executeRaw?: <T>(sqlText: string, params: readonly unknown[]) => Promise<readonly T[]>;

package/dist/{types-CQF88McG.d.cts → types-Qk2l3IkQ.d.ts}

@@ -970,7 +970,7 @@ type TransactionOptions = Readonly<{
 /**
  * Transaction backend - a backend scoped to a transaction.
  */
-type TransactionBackend = Omit<GraphBackend, "transaction" | "close">;
+type TransactionBackend = Omit<GraphBackend, "transaction" | "close" | "refreshStatistics">;
 /**
  * The GraphBackend interface abstracts database operations.
  *
@@ -1060,6 +1060,25 @@ type GraphBackend = Readonly<{
      * hit this path.
      */
     bootstrapTables?: () => Promise<void>;
+    /**
+     * Refreshes the backend's query-planner statistics.
+     *
+     * Call this once after a large initial import or bulk backfill. Without
+     * up-to-date statistics, the planner can pick suboptimal execution plans
+     * — on PostgreSQL this is the difference between a 0.5ms and a 5ms
+     * forward traversal; on SQLite it's the difference between 0.9ms and
+     * 23ms fulltext search. Autovacuum / background statistics collection
+     * will catch up eventually, but calling this explicitly after a bulk
+     * load gives you correct latencies immediately.
+     *
+     * Implementations:
+     * - SQLite runs `ANALYZE`, which populates `sqlite_stat1`
+     * - PostgreSQL runs `ANALYZE` on the TypeGraph-managed tables
+     *
+     * Safe to call at any time; costs a few tens of milliseconds on the
+     * sizes this library is designed for.
+     */
+    refreshStatistics: () => Promise<void>;
     execute: <T>(query: SQL) => Promise<readonly T[]>;
     /** Execute pre-compiled SQL text with bound parameters. Available on sync SQLite and pg backends. */
     executeRaw?: <T>(sqlText: string, params: readonly unknown[]) => Promise<readonly T[]>;

package/dist/{types-CglvhPKz.d.ts → types-qYFZ9SqD.d.ts}

@@ -1,4 +1,4 @@
-import { J as JsonPointer } from './ast-CSLbPIOC.js';
+import { J as JsonPointer } from './ast-C8S37w1A.js';
 
 /**
  * QueryProfiler types.

package/dist/{types-D23slCOA.d.cts → types-yH4_p0XB.d.cts}

@@ -1,4 +1,4 @@
-import { J as JsonPointer } from './ast-DogwbBqA.cjs';
+import { J as JsonPointer } from './ast-dgLhLOg0.cjs';
 
 /**
  * QueryProfiler types.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nicia-ai/typegraph",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "TypeScript-first embedded knowledge graph library with ontological reasoning",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -133,16 +133,28 @@
   },
   "peerDependencies": {
     "@libsql/client": ">=0.6.0",
+    "@neondatabase/serverless": ">=0.9.0 <2.0.0",
     "better-sqlite3": ">=9.0.0 <13.0.0",
     "drizzle-orm": ">=0.35.0 <1.0.0",
+    "pg": ">=8.0.0 <9.0.0",
+    "postgres": ">=3.4.0 <4.0.0",
     "zod": "^4.0.0"
   },
   "peerDependenciesMeta": {
     "@libsql/client": {
       "optional": true
     },
+    "@neondatabase/serverless": {
+      "optional": true
+    },
     "better-sqlite3": {
       "optional": true
+    },
+    "pg": {
+      "optional": true
+    },
+    "postgres": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -150,6 +162,7 @@
   },
   "devDependencies": {
     "@libsql/client": "^0.17.2",
+    "@neondatabase/serverless": "^1.1.0",
     "@stryker-mutator/core": "^9.6.1",
     "@stryker-mutator/vitest-runner": "^9.6.1",
     "@types/better-sqlite3": "^7.6.13",
@@ -161,6 +174,7 @@
     "eslint": "^10.2.1",
     "fast-check": "^4.7.0",
     "pg": "^8.20.0",
+    "postgres": "^3.4.9",
     "sqlite-vec": "^0.1.9",
     "tsd": "^0.33.0",
     "tsup": "^8.5.1",