@nicia-ai/typegraph 0.26.0 → 0.28.0

package/dist/{store-CiS_AGNH.d.ts → store-Ufc1Eoey.d.ts}

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { p as SqlDialect, ah as SqlSchema, F as FulltextStrategy, ax as ValueType, ay as PredicateExpression, az as VectorMetricType, a0 as FulltextQueryMode, Q as QueryAst, J as JsonPointer, L as FieldRef, ac as ParameterRef, G as GraphBackend, al as TransactionBackend, a5 as JsonPointerInput, am as TraversalExpansion, aA as Traversal, aB as NodePredicate, aC as ProjectedField, ab as OrderSpec, aD as GroupBySpec, a3 as HybridFusionOptions, aE as RecursiveCyclePolicy, aF as TraversalDirection$1, aG as EdgeRow, aH as NodeRow, U as AdoptedTransaction, K as AggregateExpr, aI as SelectiveField, aJ as ComposableQuery, aK as SetOperationType, aL as SetOperation, ag as SortDirection, m as JsonSchema, aM as VectorMetric } from './types-Dzkr0Eqi.js';
-import { K as KindRegistry, G as GraphDef, t as EdgeKinds, w as NodeKinds, s as AllNodeTypes, c as SchemaManagerOptions, d as SchemaValidationResult } from './manager-C3LxzPcX.js';
+import { p as SqlDialect, ah as SqlSchema, F as FulltextStrategy, ax as ValueType, ay as PredicateExpression, az as VectorMetricType, a0 as FulltextQueryMode, Q as QueryAst, J as JsonPointer, L as FieldRef, ac as ParameterRef, G as GraphBackend, al as TransactionBackend, a5 as JsonPointerInput, am as TraversalExpansion, aA as Traversal, aB as NodePredicate, aC as ProjectedField, ab as OrderSpec, aD as GroupBySpec, a3 as HybridFusionOptions, aE as RecursiveCyclePolicy, aF as TraversalDirection$1, aG as EdgeRow, aH as NodeRow, U as AdoptedTransaction, K as AggregateExpr, aI as SelectiveField, aJ as ComposableQuery, aK as SetOperationType, aL as SetOperation, ag as SortDirection, m as JsonSchema, aM as VectorMetric } from './types-CQ7xXJMP.js';
+import { K as KindRegistry, G as GraphDef, u as EdgeKinds, x as NodeKinds, t as AllNodeTypes, c as SchemaManagerOptions, d as SchemaValidationResult } from './manager-ehLTTNq0.js';
 import { A as AnyEdgeType, N as NodeType, T as TemporalMode, e as EdgeType, E as EdgeRegistration, h as EdgeId, m as NodeId, b as NodeRegistration, K as KindEntity, f as Cardinality, k as EndpointExistence, d as KindAnnotations, o as UniquenessScope, g as Collation, G as GraphExtension } from './extension-types-B78CZfA5.js';
 import { SQL } from 'drizzle-orm';
 import { b as MaterializeIndexesOptions, M as MaterializeIndexesResult } from './materialize-indexes-DFavFQah.js';
@@ -2920,6 +2920,14 @@ type HybridVectorOptions = Readonly<{
     k?: number;
     /** Minimum similarity to include (units depend on metric). */
     minScore?: number;
+    /**
+     * HNSW search frontier for this query (pgvector `hnsw.ef_search`).
+     * The vector side over-fetches `k` (default `4 * limit`) candidates;
+     * `efSearch` must be `>= k` for the index to surface that many
+     * neighbors, and ~2–4× `k` is the high-recall target. Postgres HNSW
+     * only — no-op elsewhere. See `VectorSearchOptions.efSearch`.
+     */
+    efSearch?: number;
 }>;
 /**
  * Options for the standalone `store.search.vector` path. Mirrors the
@@ -2937,6 +2945,22 @@ type VectorSearchOptions = Readonly<{
     metric?: VectorMetric;
     /** Minimum similarity to include (units depend on metric). */
     minScore?: number;
+    /**
+     * HNSW search frontier for this query (pgvector `hnsw.ef_search`).
+     * Sizes the dynamic candidate list the index scan maintains — higher
+     * trades latency for recall. The floor for the index to surface
+     * `limit` neighbors is `efSearch >= limit`; ~2–4× is the high-recall
+     * target on million-scale corpora. Lets a latency-sensitive
+     * interactive path and a recall-sensitive batch path share one
+     * connection pool, tuning per query rather than per session.
+     *
+     * Postgres HNSW only: applied transaction-locally via `SET LOCAL`.
+     * sqlite-vec has no equivalent frontier knob and ignores it; Postgres
+     * backends without transactions (`drizzle-orm/neon-http`) ignore it
+     * with a one-time warning. Must be a positive integer; pgvector caps
+     * it at 1000.
+     */
+    efSearch?: number;
 }>;
 type HybridFulltextOptions = Readonly<{
     query: string;
@@ -3766,5 +3790,47 @@ declare function createStore<G extends GraphDef>(graph: G, backend: GraphBackend
  * ```
  */
 declare function createStoreWithSchema<G extends GraphDef>(graph: G, backend: GraphBackend, options?: StoreOptions & SchemaManagerOptions): Promise<[Store<G>, SchemaValidationResult]>;
+/**
+ * Creates a Store after **verifying** that the database is at the same
+ * schema version as the code graph — without running any DDL, bootstrap,
+ * or marker writes. The runtime counterpart of `createStoreWithSchema`
+ * for the deployment model in "Database roles & least privilege":
+ *
+ * - **`createStoreWithSchema(graph, backend)`** runs DDL (bootstrap,
+ *   safe auto-migrations, durable contribution materialization). Run it
+ *   once at startup under a privileged role that holds `CREATE` / DDL.
+ * - **`createVerifiedStore(graph, backend)`** is the zero-DDL runtime
+ *   attach with a verification gate. Throws `MigrationError` when the
+ *   persisted schema is behind the code graph (any pending change, safe
+ *   or breaking), `ConfigurationError` when no schema has been
+ *   initialized, or `StoreNotInitializedError` when the schema is
+ *   current but the runtime-contribution markers are missing/stale.
+ *   The runtime can use a least-privilege, DML-only database role.
+ * - **`createStore(graph, backend)`** is the same zero-DDL attach
+ *   *without* the verification gate — fastest, but schema drift goes
+ *   undetected until a hot-path operation trips.
+ *
+ * Folds any persisted graph-extension document into the supplied graph
+ * before building the Store, just like `createStoreWithSchema`.
+ *
+ * @param graph - The graph definition
+ * @param backend - The database backend
+ * @param options - Optional store configuration
+ * @returns A tuple of [store, validationResult] — `result.status` is
+ *   always `"unchanged"` on success
+ *
+ * @example
+ * ```typescript
+ * // Runtime — least-privilege, DML-only role. Zero DDL.
+ * const [store, result] = await createVerifiedStore(graph, backend);
+ * // result.status === "unchanged" — the privileged migrator is current.
+ * ```
+ *
+ * @throws ConfigurationError if no schema has been initialized.
+ * @throws MigrationError if the persisted schema is behind the code graph.
+ * @throws StoreNotInitializedError if runtime-contribution markers are
+ *   missing/stale/failed for this graph on this connection.
+ */
+declare function createVerifiedStore<G extends GraphDef>(graph: G, backend: GraphBackend, options?: StoreOptions): Promise<[Store<G>, SchemaValidationResult]>;
 
-export { type MaterializeRemovalsOptions as $, type AliasMap as A, type BaseTraversalOptions as B, type CreateQueryBuilderOptions as C, DEFAULT_SEARCHABLE_LANGUAGE as D, type EdgeAliasMap as E, type EmbeddingSchema as F, type EmbeddingValue as G, ExecutableAggregateQuery as H, ExecutableQuery as I, type FieldAccessor as J, type FulltextSearchHit as K, type FulltextSearchOptions as L, type GetOrCreateAction as M, type GraphAlgorithms as N, type GraphEdgeCollections as O, type GraphNodeCollections as P, QueryBuilder as Q, type HookContext as R, Store as S, TraversalBuilder as T, type HybridFulltextOptions as U, type HybridSearchHit as V, type HybridSearchOptions as W, type HybridVectorOptions as X, type IfExistsMode as Y, type KindIntrospection as Z, type MaterializeRemovalsEntry as _, type AggregateResult as a, getSearchableMetadata as a$, type MaterializeRemovalsResult as a0, type NeighborsOptions as a1, type Node as a2, type NodeAccessor as a3, type NodeAlias as a4, type NodeCollection as a5, type NodeGetOrCreateByConstraintOptions as a6, type NodeGetOrCreateByConstraintResult as a7, type NodeIdentifier as a8, type NodeRef as a9, type StoreProjection as aA, type StoreRef as aB, StoreSearch as aC, type StreamOptions as aD, type SubgraphEdgeResult as aE, type SubgraphNodeResult as aF, type SubgraphOptions as aG, type SubgraphResult as aH, type SubsetEdge as aI, type SubsetNode as aJ, type TemporalAlgorithmOptions as aK, type TransactionContext as aL, type TraversalDirection as aM, type TypedEdgeCollection as aN, UnionableQuery as aO, type UniqueIntrospection as aP, type UpdateEdgeInput as aQ, type UpdateNodeInput as aR, type VectorSearchHit as aS, type VectorSearchOptions as aT, createStore as aU, createStoreWithSchema as aV, defineSubgraphProject as aW, embedding as aX, exists as aY, fieldRef as aZ, getEmbeddingDimensions as a_, type OntologyIntrospection as aa, type OperationHookContext as ab, type PaginateOptions as ac, type PaginatedResult as ad, type PathNode as ae, type Predicate as af, PreparedQuery as ag, type PropsAccessor as ah, type QueryHookContext as ai, type QueryOptions as aj, type ReachableNode as ak, type ReachableOptions as al, type RebuildFulltextOptions as am, type RebuildFulltextResult as an, type RecursiveTraversalOptions as ao, type SchemaIntrospection as ap, type SearchableMetadata as aq, type SearchableOptions as ar, type SearchableSchema as as, type SelectContext as at, type SelectableEdge as au, type SelectableNode as av, type ShortestPathOptions as aw, type ShortestPathResult as ax, type StoreHooks as ay, type StoreOptions as az, type AlgorithmCyclePolicy as b, inSubquery as b0, isEmbeddingSchema as b1, isParameterRef as b2, isSearchableSchema as b3, notExists as b4, notInSubquery as b5, param as b6, searchable as b7, type AnyEdge as c, type AnyNode as d, type BatchResults as e, type BatchableQuery as f, type ConstraintNames as g, type CreateEdgeInput as h, type CreateNodeInput as i, type DegreeOptions as j, type DynamicEdgeAccessor as k, type DynamicEdgeCollection as l, type DynamicEdgeType as m, type DynamicFieldBuilder as n, type DynamicNodeAccessor as o, type DynamicNodeCollection as p, type DynamicNodeType as q, type DynamicSelectableEdge as r, type DynamicSelectableNode as s, type Edge as t, type EdgeAccessor as u, type EdgeCollection as v, type EdgeFindByEndpointsOptions as w, type EdgeGetOrCreateByEndpointsOptions as x, type EdgeGetOrCreateByEndpointsResult as y, type EdgeIntrospection as z };
+export { type MaterializeRemovalsOptions as $, type AliasMap as A, type BaseTraversalOptions as B, type CreateQueryBuilderOptions as C, DEFAULT_SEARCHABLE_LANGUAGE as D, type EdgeAliasMap as E, type EmbeddingSchema as F, type EmbeddingValue as G, ExecutableAggregateQuery as H, ExecutableQuery as I, type FieldAccessor as J, type FulltextSearchHit as K, type FulltextSearchOptions as L, type GetOrCreateAction as M, type GraphAlgorithms as N, type GraphEdgeCollections as O, type GraphNodeCollections as P, QueryBuilder as Q, type HookContext as R, Store as S, TraversalBuilder as T, type HybridFulltextOptions as U, type HybridSearchHit as V, type HybridSearchOptions as W, type HybridVectorOptions as X, type IfExistsMode as Y, type KindIntrospection as Z, type MaterializeRemovalsEntry as _, type AggregateResult as a, getEmbeddingDimensions as a$, type MaterializeRemovalsResult as a0, type NeighborsOptions as a1, type Node as a2, type NodeAccessor as a3, type NodeAlias as a4, type NodeCollection as a5, type NodeGetOrCreateByConstraintOptions as a6, type NodeGetOrCreateByConstraintResult as a7, type NodeIdentifier as a8, type NodeRef as a9, type StoreProjection as aA, type StoreRef as aB, StoreSearch as aC, type StreamOptions as aD, type SubgraphEdgeResult as aE, type SubgraphNodeResult as aF, type SubgraphOptions as aG, type SubgraphResult as aH, type SubsetEdge as aI, type SubsetNode as aJ, type TemporalAlgorithmOptions as aK, type TransactionContext as aL, type TraversalDirection as aM, type TypedEdgeCollection as aN, UnionableQuery as aO, type UniqueIntrospection as aP, type UpdateEdgeInput as aQ, type UpdateNodeInput as aR, type VectorSearchHit as aS, type VectorSearchOptions as aT, createStore as aU, createStoreWithSchema as aV, createVerifiedStore as aW, defineSubgraphProject as aX, embedding as aY, exists as aZ, fieldRef as a_, type OntologyIntrospection as aa, type OperationHookContext as ab, type PaginateOptions as ac, type PaginatedResult as ad, type PathNode as ae, type Predicate as af, PreparedQuery as ag, type PropsAccessor as ah, type QueryHookContext as ai, type QueryOptions as aj, type ReachableNode as ak, type ReachableOptions as al, type RebuildFulltextOptions as am, type RebuildFulltextResult as an, type RecursiveTraversalOptions as ao, type SchemaIntrospection as ap, type SearchableMetadata as aq, type SearchableOptions as ar, type SearchableSchema as as, type SelectContext as at, type SelectableEdge as au, type SelectableNode as av, type ShortestPathOptions as aw, type ShortestPathResult as ax, type StoreHooks as ay, type StoreOptions as az, type AlgorithmCyclePolicy as b, getSearchableMetadata as b0, inSubquery as b1, isEmbeddingSchema as b2, isParameterRef as b3, isSearchableSchema as b4, notExists as b5, notInSubquery as b6, param as b7, searchable as b8, type AnyEdge as c, type AnyNode as d, type BatchResults as e, type BatchableQuery as f, type ConstraintNames as g, type CreateEdgeInput as h, type CreateNodeInput as i, type DegreeOptions as j, type DynamicEdgeAccessor as k, type DynamicEdgeCollection as l, type DynamicEdgeType as m, type DynamicFieldBuilder as n, type DynamicNodeAccessor as o, type DynamicNodeCollection as p, type DynamicNodeType as q, type DynamicSelectableEdge as r, type DynamicSelectableNode as s, type Edge as t, type EdgeAccessor as u, type EdgeCollection as v, type EdgeFindByEndpointsOptions as w, type EdgeGetOrCreateByEndpointsOptions as x, type EdgeGetOrCreateByEndpointsResult as y, type EdgeIntrospection as z };

package/dist/{types-Cars4JZ1.d.ts → types-B-sJJ4GQ.d.ts}

@@ -1,5 +1,5 @@
 import { K as KindEntity } from './extension-types-B78CZfA5.js';
-import { J as JsonPointer } from './types-Dzkr0Eqi.js';
+import { J as JsonPointer } from './types-CQ7xXJMP.js';
 
 /**
  * QueryProfiler types.

package/dist/{types-DZPBXZOK.d.cts → types-CMQymcwk.d.cts}

@@ -814,6 +814,17 @@ type VectorSearchParams = Readonly<{
     metric: VectorMetric;
     limit: number;
     minScore?: number;
+    /**
+     * HNSW search frontier for this query (pgvector `hnsw.ef_search`).
+     * Sizes the dynamic candidate list the index scan maintains: higher
+     * trades latency for recall. The floor for the over-fetch to fill its
+     * candidate set is `efSearch >= limit`; ~2–4× is the high-recall
+     * target. Applied transaction-locally (`SET LOCAL`) on the Postgres
+     * HNSW path only. No-op on backends without an HNSW frontier knob
+     * (sqlite-vec) and ignored — with a one-time warning — on Postgres
+     * backends without transactions (e.g. `drizzle-orm/neon-http`).
+     */
+    efSearch?: number;
 }>;
 /**
  * Result from a vector similarity search.

package/dist/{types-Dzkr0Eqi.d.ts → types-CQ7xXJMP.d.ts}

@@ -814,6 +814,17 @@ type VectorSearchParams = Readonly<{
     metric: VectorMetric;
     limit: number;
     minScore?: number;
+    /**
+     * HNSW search frontier for this query (pgvector `hnsw.ef_search`).
+     * Sizes the dynamic candidate list the index scan maintains: higher
+     * trades latency for recall. The floor for the over-fetch to fill its
+     * candidate set is `efSearch >= limit`; ~2–4× is the high-recall
+     * target. Applied transaction-locally (`SET LOCAL`) on the Postgres
+     * HNSW path only. No-op on backends without an HNSW frontier knob
+     * (sqlite-vec) and ignored — with a one-time warning — on Postgres
+     * backends without transactions (e.g. `drizzle-orm/neon-http`).
+     */
+    efSearch?: number;
 }>;
 /**
  * Result from a vector similarity search.

package/dist/{types-CF7nDH3q.d.cts → types-CmUA9sal.d.cts}

@@ -1,5 +1,5 @@
 import { K as KindEntity } from './extension-types-B78CZfA5.cjs';
-import { J as JsonPointer } from './types-DZPBXZOK.cjs';
+import { J as JsonPointer } from './types-CMQymcwk.cjs';
 
 /**
  * QueryProfiler types.

package/dist/{where-BmtjfWuS.d.cts → where-5zf15aFZ.d.cts}

@@ -1,5 +1,5 @@
 import { A as AnyEdgeType, N as NodeType } from './extension-types-B78CZfA5.cjs';
-import { E as EdgeIndexConfig, c as EdgeIndexDeclaration, N as NodeIndexConfig, d as NodeIndexDeclaration, e as IndexWhereExpression } from './types-DZPBXZOK.cjs';
+import { E as EdgeIndexConfig, c as EdgeIndexDeclaration, N as NodeIndexConfig, d as NodeIndexDeclaration, e as IndexWhereExpression } from './types-CMQymcwk.cjs';
 
 declare function defineNodeIndex<N extends NodeType>(node: N, config: NodeIndexConfig<N>): NodeIndexDeclaration;
 declare function defineEdgeIndex<E extends AnyEdgeType>(edge: E, config: EdgeIndexConfig<E>): EdgeIndexDeclaration;

package/dist/{where-kk1Zz2En.d.ts → where-CtrLu1Zf.d.ts}

@@ -1,5 +1,5 @@
 import { A as AnyEdgeType, N as NodeType } from './extension-types-B78CZfA5.js';
-import { E as EdgeIndexConfig, c as EdgeIndexDeclaration, N as NodeIndexConfig, d as NodeIndexDeclaration, e as IndexWhereExpression } from './types-Dzkr0Eqi.js';
+import { E as EdgeIndexConfig, c as EdgeIndexDeclaration, N as NodeIndexConfig, d as NodeIndexDeclaration, e as IndexWhereExpression } from './types-CQ7xXJMP.js';
 
 declare function defineNodeIndex<N extends NodeType>(node: N, config: NodeIndexConfig<N>): NodeIndexDeclaration;
 declare function defineEdgeIndex<E extends AnyEdgeType>(edge: E, config: EdgeIndexConfig<E>): EdgeIndexDeclaration;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nicia-ai/typegraph",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "TypeScript-first embedded knowledge graph library with ontological reasoning",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -121,7 +121,7 @@
     "nanoid": "^5.1.11"
   },
   "devDependencies": {
-    "@cloudflare/vitest-pool-workers": "^0.16.6",
+    "@cloudflare/vitest-pool-workers": "^0.16.7",
     "@libsql/client": "^0.17.3",
     "@neondatabase/serverless": "^1.1.0",
     "@stryker-mutator/core": "^9.6.1",
@@ -129,18 +129,18 @@
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^24.12.0",
     "@types/pg": "^8.20.0",
-    "@vitest/coverage-v8": "^4.1.5",
-    "better-sqlite3": "^12.9.0",
+    "@vitest/coverage-v8": "^4.1.7",
+    "better-sqlite3": "^12.10.0",
     "drizzle-orm": "^0.45.2",
-    "eslint": "^10.3.0",
-    "fast-check": "^4.7.0",
-    "pg": "^8.20.0",
+    "eslint": "^10.4.0",
+    "fast-check": "^4.8.0",
+    "pg": "^8.21.0",
     "postgres": "^3.4.9",
     "sqlite-vec": "^0.1.9",
     "tsd": "^0.33.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.5",
+    "vitest": "^4.1.7",
     "zod": "^4.4.3",
     "@typegraph/eslint-config": "0.1.0"
   },