@nicia-ai/typegraph 0.19.0 → 0.21.0

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

@@ -1,8 +1,7 @@
-import { S as SqlSchema, G as GraphBackend, T as TransactionBackend, E as EdgeRow, N as NodeRow } from './types-B3mmOMJV.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-Bj1UEnhE.cjs';
-import { S as SqlDialect, N as NodeType, A as AnyEdgeType, T as TemporalMode, E as EdgeType, d as EdgeRegistration, b as EdgeId, g as NodeId, i as NodeRegistration } from './types-DMzKq0d5.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-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 { 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, 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-Bh2NDeaK.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-DogwbBqA.cjs';
 import { SQL } from 'drizzle-orm';
 
 /**
@@ -86,6 +85,75 @@ declare function isEmbeddingSchema(value: unknown): value is EmbeddingSchema;
  */
 declare function getEmbeddingDimensions(schema: z.ZodType): number | undefined;
 
+/**
+ * Searchable string type for fulltext search.
+ *
+ * `searchable()` attaches `SearchableMetadata` to a plain Zod string so
+ * the schema introspector and fulltext-sync layer can keep the fulltext
+ * index in sync with node data.
+ *
+ * The metadata is preserved by Zod's `.meta()` across refinements
+ * (`.min(1)`, `.trim()`, `.regex(...)`) and wrapper types (`.optional()`,
+ * `.nullable()`, `.default(...)`, pipes) — `getSearchableMetadata()` walks
+ * these variants so runtime indexing works whether or not a user chains
+ * additional modifiers.
+ *
+ * `$fulltext` is exposed on every `NodeAccessor` at the type level; a
+ * runtime guard throws a clear error if you call `.matches()` on an
+ * alias whose node kind has no `searchable()` fields. This is simpler
+ * and more predictable than a type-level brand that silently disappears
+ * behind `.min(1)`.
+ *
+ * @example
+ * ```typescript
+ * const Document = defineNode("Document", {
+ *   schema: z.object({
+ *     title: searchable({ language: "english" }),
+ *     body: searchable().min(1),
+ *     authorId: z.string(),
+ *   }),
+ * });
+ * ```
+ */
+
+declare const SEARCHABLE_FIELD_KEY: "_searchableField";
+declare const DEFAULT_SEARCHABLE_LANGUAGE: "english";
+/**
+ * Searchable field metadata attached to a Zod schema.
+ */
+type SearchableMetadata = Readonly<{
+    /**
+     * Language for stemming / tokenization.
+     * Postgres: passed to `to_tsvector(regconfig, ...)`.
+     * SQLite FTS5: tokenizer is fixed at table-create time, so the
+     * language is recorded but not applied per-row.
+     */
+    language: string;
+}>;
+/**
+ * Branded Zod string schema. The `SEARCHABLE_FIELD_KEY` marker is
+ * attached both as a direct property (fast runtime check) and via Zod's
+ * `.meta()` (so it survives `.min()`, `.trim()`, etc.).
+ */
+type SearchableSchema = z.ZodString & Readonly<{
+    [SEARCHABLE_FIELD_KEY]: SearchableMetadata;
+}>;
+type SearchableOptions = Readonly<{
+    language?: string;
+}>;
+/**
+ * Creates a Zod string schema tagged as fulltext-searchable.
+ *
+ * The returned schema passes runtime validation unchanged — the tag only
+ * affects how TypeGraph treats the field for indexing and search. Pair
+ * with `.optional()` / `.nullable()` / `.min()` / `.trim()` exactly like
+ * any other Zod string; `getSearchableMetadata()` finds the metadata
+ * through all of them.
+ */
+declare function searchable(options?: SearchableOptions): SearchableSchema;
+declare function isSearchableSchema(value: unknown): value is SearchableSchema;
+declare function getSearchableMetadata(schema: z.ZodType): SearchableMetadata | undefined;
+
 /**
  * Query Compiler Module
  *
@@ -101,6 +169,14 @@ type CompileQueryOptions = Readonly<{
     dialect?: SqlDialect | undefined;
     /** SQL schema configuration for table names. Defaults to standard names. */
     schema?: SqlSchema | undefined;
+    /**
+     * Fulltext strategy override. When set, overrides the dialect's
+     * default fulltext strategy for `$fulltext.matches()` compilation.
+     * Callers typically read this from `backend.fulltextStrategy` so a
+     * backend-declared strategy (e.g. ParadeDB) wins over the dialect
+     * default (tsvector).
+     */
+    fulltextStrategy?: FulltextStrategy | undefined;
 }>;
 
 type FieldTypeInfo = Readonly<{
@@ -111,14 +187,29 @@ type FieldTypeInfo = Readonly<{
     recordValueType?: FieldTypeInfo | undefined;
     /** For embedding types: the number of dimensions */
     dimensions?: number | undefined;
+    /** For fulltext-searchable string types: field-level metadata */
+    searchable?: SearchableMetadata | 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;
+    /**
+     * True iff every kind in `kindNames` has at least one `searchable()`
+     * field. For polymorphic aliases, `$fulltext` is available only when
+     * every resolved kind has searchable content — otherwise `.matches()`
+     * would silently miss some kinds.
+     */
+    hasSearchableField: (kindNames: readonly string[]) => boolean;
 }>;
 
+/**
+ * Predicate builders for TypeGraph queries.
+ *
+ * Provides a fluent API for building type-safe predicates.
+ */
+
 /**
  * A chainable predicate that can be combined with AND/OR.
  */
@@ -151,6 +242,34 @@ declare function param(name: string): ParameterRef;
  * Type guard for ParameterRef values.
  */
 declare function isParameterRef(value: unknown): value is ParameterRef;
+/**
+ * Options for the `$fulltext.matches()` predicate.
+ *
+ * Note the term glossary used throughout TypeGraph search:
+ * - **`k`** (the positional argument on `.matches(query, k)`) is the
+ *   per-predicate top-k cap applied inside the fulltext CTE.
+ * - **`limit`** (on store-level `search.fulltext` / `search.hybrid` and
+ *   on the query builder) is the final result count returned to the
+ *   caller after any fusion.
+ */
+type MatchesOptions = Readonly<{
+    /**
+     * Parse mode for the query string. Default: "websearch".
+     *
+     * - "websearch": Google-style syntax (quoted phrases, `-excluded`, `OR`).
+     *   Postgres: `websearch_to_tsquery`. SQLite: translated to FTS5 MATCH.
+     * - "phrase": treats the whole query as a phrase.
+     * - "plain": splits on whitespace and ANDs terms.
+     * - "raw": dialect-native syntax passed through unchanged.
+     */
+    mode?: FulltextQueryMode;
+    /**
+     * Language override. Default: per-row language as stored at insert time.
+     */
+    language?: string;
+    /** Minimum relevance score to include. */
+    minScore?: number;
+}>;
 /**
  * Options for the similarTo method.
  */
@@ -174,6 +293,17 @@ type FieldRefOptions = Readonly<{
     elementType?: ValueType | undefined;
 }>;
 declare function fieldRef(alias: string, path: readonly string[], options?: FieldRefOptions): FieldRef;
+/**
+ * Node-level fulltext accessor. Always present on the `NodeAccessor`
+ * type — a runtime check throws a clear error if the node kind has no
+ * `searchable()` fields. `k` is the top-k cap applied inside the
+ * fulltext CTE; defaults to `DEFAULT_FULLTEXT_MATCH_K`. Use a larger
+ * value when feeding the result into RRF (`.fuseWith()` /
+ * `store.search.hybrid()`).
+ */
+type FulltextAccessor = Readonly<{
+    matches: (query: string, k?: number, options?: MatchesOptions) => Predicate;
+}>;
 /**
  * Creates an EXISTS subquery predicate.
  * Returns true if the subquery returns at least one row.
@@ -273,7 +403,7 @@ type BatchResults<Queries extends readonly BatchableQuery<unknown>[]> = {
  * // 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;
+type ValidEdgeTargets<G extends GraphDef, EK extends keyof G["edges"] & string, Dir extends TraversalDirection$1> = G["edges"][EK] extends EdgeRegistration ? Dir extends "out" ? G["edges"][EK]["to"][number]["kind"] : G["edges"][EK]["from"][number]["kind"] : never;
 /**
  * A node alias with its associated type.
  */
@@ -421,10 +551,15 @@ type ObjectFieldAccessor<T> = BaseFieldAccessor & Readonly<{
  * Properties are available at the top level for ergonomic access:
  * - `n.name` instead of `n.props.name`
  * - System fields: `n.id`, `n.kind`
+ * - Fulltext: `n.$fulltext.matches(...)` — throws at query build time if
+ *   the node kind has no `searchable()` fields. Exposed at the type
+ *   level on every accessor so refinements like
+ *   `searchable().min(1)` do not make it disappear.
  */
 type NodeAccessor<N extends NodeType> = Readonly<{
     id: StringFieldAccessor;
     kind: StringFieldAccessor;
+    $fulltext: FulltextAccessor;
 }> & PropsAccessor<N>;
 /**
  * Creates typed field accessors for an edge kind's properties.
@@ -591,6 +726,7 @@ type QueryBuilderState = Readonly<{
     asOf: string | undefined;
     groupBy: GroupBySpec | undefined;
     having: PredicateExpression | undefined;
+    fusion: HybridFusionOptions | undefined;
 }>;
 /**
  * Options for creating a query builder.
@@ -1485,6 +1621,13 @@ type SubgraphOptions<G extends GraphDef, EK extends EdgeKinds<G>, NK extends Nod
     direction?: "out" | "both";
     /** Cycle policy — reuse RecursiveCyclePolicy (default: "prevent"). */
     cyclePolicy?: RecursiveCyclePolicy;
+    /**
+     * Temporal mode applied to both nodes and edges along the traversal and in
+     * the hydrated result. Defaults to `graph.defaults.temporalMode`.
+     */
+    temporalMode?: TemporalMode;
+    /** ISO-8601 timestamp used when `temporalMode === "asOf"`. */
+    asOf?: string;
     /**
      * Optional field-level projection per node/edge kind.
      *
@@ -1866,7 +2009,7 @@ 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, DC extends boolean | string = false, PC extends boolean | string = false, RecAliases extends RecursiveAliasMap = {}> {
+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$1 = "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, inverseEdgeKinds?: readonly string[], optional?: Optional, variableLength?: VariableLengthState, pendingEdgePredicates?: readonly NodePredicate[]);
     /**
@@ -2045,6 +2188,30 @@ declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = {}, Ed
      * @param predicate - A predicate expression to filter groups
      */
     having(predicate: PredicateExpression): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>;
+    /**
+     * Sets fusion parameters for hybrid (vector + fulltext) queries.
+     *
+     * Applies only when the query contains both a `.similarTo()` and a
+     * `.$fulltext.matches()` predicate. Without this call, the default is
+     * RRF with k=60 and equal weights. A mismatch between `.fuseWith()`
+     * configuration and the predicates on the query is caught during
+     * compilation, not here.
+     *
+     * @example
+     * ```typescript
+     * store.query()
+     *   .from("Document", "d")
+     *   .whereNode("d", d =>
+     *     d.$fulltext.matches("renewable energy", 50)
+     *       .and(d.embedding.similarTo(vec, 50))
+     *       .and(d.tenantId.eq(tenant))
+     *   )
+     *   .fuseWith({ k: 60, weights: { fulltext: 1.5 } })
+     *   .limit(10)
+     *   .execute();
+     * ```
+     */
+    fuseWith(options: HybridFusionOptions): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>;
     /**
      * Applies a query fragment to transform this builder.
      *
@@ -2073,6 +2240,409 @@ declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = {}, Ed
     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>;
 }
 
+/**
+ * Shared types for Tier 1 graph algorithms.
+ *
+ * Algorithms operate over one or more edge kinds and may traverse edges
+ * in the forward direction ("out"), reverse ("in"), or undirected ("both").
+ */
+
+/**
+ * Direction of edge traversal.
+ *
+ * - `"out"` — follow edges from source to target (default)
+ * - `"in"` — follow edges from target back to source
+ * - `"both"` — undirected traversal over either endpoint
+ */
+type TraversalDirection = "out" | "in" | "both";
+/**
+ * Cycle-handling strategy during recursive traversal.
+ *
+ * - `"prevent"` — skip any node already on the current path (default).
+ *   Guarantees termination even in cyclic graphs.
+ * - `"allow"` — permit revisiting nodes. Only safe with a bounded `maxHops`.
+ *
+ * Aliased to `RecursiveCyclePolicy` so algorithms and query-builder traversals
+ * share a single canonical union.
+ */
+type AlgorithmCyclePolicy = RecursiveCyclePolicy;
+/**
+ * Temporal filter options shared by every algorithm.
+ *
+ * Algorithms honor the same temporal model as the rest of the store: both
+ * nodes and edges are filtered according to the resolved mode. `asOf` is
+ * only consulted when the resolved mode is `"asOf"`. If neither option is
+ * supplied, the algorithm falls back to `graph.defaults.temporalMode`.
+ */
+type TemporalAlgorithmOptions = Readonly<{
+    /** Temporal mode. Defaults to the graph's configured default. */
+    temporalMode?: TemporalMode;
+    /**
+     * ISO-8601 timestamp used when `temporalMode` is `"asOf"`. Required in that
+     * mode; ignored in all others.
+     */
+    asOf?: string;
+}>;
+/**
+ * Base options for traversal-style algorithms.
+ */
+type BaseTraversalOptions<G extends GraphDef> = TemporalAlgorithmOptions & Readonly<{
+    /** Edge kinds to follow. At least one kind is required. */
+    edges: readonly EdgeKinds<G>[];
+    /**
+     * Maximum number of hops to traverse. Defaults to 10.
+     * Must be between 1 and 1000.
+     */
+    maxHops?: number;
+    /** Direction of traversal (default: `"out"`). */
+    direction?: TraversalDirection;
+    /** Cycle policy (default: `"prevent"`). */
+    cyclePolicy?: AlgorithmCyclePolicy;
+}>;
+/**
+ * A node reached during traversal, annotated with the shortest depth at which
+ * it was first discovered.
+ */
+type ReachableNode = Readonly<{
+    id: string;
+    kind: string;
+    /** Number of edges traversed from the source. 0 for the source itself. */
+    depth: number;
+}>;
+/**
+ * A node along a shortest path. Endpoints are included.
+ */
+type PathNode = Readonly<{
+    id: string;
+    kind: string;
+}>;
+/**
+ * Result of `shortestPath`: the ordered node sequence and its length in hops.
+ */
+type ShortestPathResult = Readonly<{
+    /** Ordered nodes from source to target (inclusive). */
+    nodes: readonly PathNode[];
+    /** Number of edges traversed. Equals `nodes.length - 1`. */
+    depth: number;
+}>;
+/**
+ * Options for `shortestPath` and `canReach`. Reuses the base traversal
+ * options; cycle policy defaults to `"prevent"` since both algorithms only
+ * care about the first time a target is reached.
+ */
+type ShortestPathOptions<G extends GraphDef> = BaseTraversalOptions<G>;
+/**
+ * Options for `reachable`.
+ *
+ * Returns every node reachable from the source within `maxHops`, each
+ * annotated with its minimum discovered depth. `depth: 0` refers to the
+ * source itself and is included unless `excludeSource` is `true`.
+ */
+type ReachableOptions<G extends GraphDef> = BaseTraversalOptions<G> & Readonly<{
+    /** Exclude the source node from the result set (default: `false`). */
+    excludeSource?: boolean;
+}>;
+/**
+ * Options for `neighbors`.
+ *
+ * Like `reachable`, but the parameter is named `depth` for readability —
+ * "2-hop neighbors" reads more naturally than "reachable with maxHops=2".
+ * The source is always excluded.
+ */
+type NeighborsOptions<G extends GraphDef> = TemporalAlgorithmOptions & Readonly<{
+    /** Edge kinds to follow. At least one kind is required. */
+    edges: readonly EdgeKinds<G>[];
+    /** Maximum neighborhood depth (default: 1). Must be between 1 and 1000. */
+    depth?: number;
+    /** Direction of traversal (default: `"out"`). */
+    direction?: TraversalDirection;
+    /** Cycle policy (default: `"prevent"`). */
+    cyclePolicy?: AlgorithmCyclePolicy;
+}>;
+/**
+ * Options for `degree`.
+ *
+ * Counts active edges incident to a node. With `direction: "both"`, an edge
+ * that happens to be a self-loop (from === to) is counted once, not twice.
+ */
+type DegreeOptions<G extends GraphDef> = TemporalAlgorithmOptions & Readonly<{
+    /**
+     * Edge kinds to count. If omitted, counts across all edge kinds in the
+     * graph.
+     */
+    edges?: readonly EdgeKinds<G>[];
+    /** Direction (default: `"both"`). */
+    direction?: TraversalDirection;
+}>;
+
+/**
+ * Raw node id or any object with an `id: string` field. Covers `Node`,
+ * `NodeRef`, and the lightweight `ReachableNode` / `PathNode` shapes
+ * returned by the algorithms themselves.
+ *
+ * Deliberately kind-agnostic: graph algorithms don't constrain the source
+ * node's kind — you can start a traversal from any node reachable via the
+ * given edge kinds. `NodeRef<N>` exists for the edge-endpoint case where
+ * kind *is* load-bearing; using it here would paint a constraint onto a
+ * contract that doesn't need one and would reject common patterns like
+ * passing `ReachableNode` / cache entries / `{ id }` records straight
+ * through.
+ */
+type NodeIdentifier = string | Readonly<{
+    id: string;
+}>;
+type GraphAlgorithms<G extends GraphDef> = Readonly<{
+    /**
+     * Finds the shortest directed path from `from` to `to` using the given
+     * edge kinds. Returns `undefined` when no path exists within `maxHops`.
+     *
+     * @example
+     * ```typescript
+     * const path = await store.algorithms.shortestPath(alice, bob, {
+     *   edges: ["knows"],
+     *   maxHops: 6,
+     * });
+     * if (path) {
+     *   console.log(`${path.depth} hops via`, path.nodes.map((n) => n.id));
+     * }
+     * ```
+     */
+    shortestPath: (from: NodeIdentifier, to: NodeIdentifier, options: ShortestPathOptions<G>) => Promise<ShortestPathResult | undefined>;
+    /**
+     * Returns every node reachable from `from` within `maxHops` edges of the
+     * allowed kinds. Each node carries its minimum discovered depth.
+     */
+    reachable: (from: NodeIdentifier, options: ReachableOptions<G>) => Promise<readonly ReachableNode[]>;
+    /**
+     * Fast boolean check: is `to` reachable from `from` within `maxHops`
+     * edges? Short-circuits the underlying recursive CTE with `LIMIT 1`.
+     */
+    canReach: (from: NodeIdentifier, to: NodeIdentifier, options: BaseTraversalOptions<G>) => Promise<boolean>;
+    /**
+     * Returns the k-hop neighborhood of a node. The source is always
+     * excluded. `depth` defaults to 1, matching the common "immediate
+     * neighbors" interpretation.
+     */
+    neighbors: (node: NodeIdentifier, options: NeighborsOptions<G>) => Promise<readonly ReachableNode[]>;
+    /**
+     * Counts active edges incident to `node`.
+     *
+     * With `direction: "both"` (default), self-loops contribute once.
+     */
+    degree: (node: NodeIdentifier, options?: DegreeOptions<G>) => Promise<number>;
+}>;
+
+type RebuildFulltextOptions = Readonly<{
+    /** Page size. Must be a positive integer. Default: 500. */
+    pageSize?: number;
+    /**
+     * Maximum number of skipped node IDs to include in the `skippedIds`
+     * array. Default: 10,000. Set higher to collect the full list when
+     * investigating systemic corruption; set lower when `processed` is
+     * all you care about. The `skipped` total is always accurate.
+     */
+    maxSkippedIds?: number;
+}>;
+type RebuildFulltextResult = Readonly<{
+    /** Node kinds that were rebuilt (those with at least one searchable field). */
+    kinds: readonly string[];
+    /** Total nodes scanned. */
+    processed: number;
+    /** Fulltext upsert operations executed. */
+    upserted: number;
+    /** Fulltext delete operations executed (soft-deleted or all-empty nodes). */
+    cleared: number;
+    /**
+     * Nodes skipped due to corrupt or non-object `props` (not counted in
+     * upserted/cleared).
+     */
+    skipped: number;
+    /**
+     * IDs of skipped nodes, capped at 10,000 entries so pathological
+     * corruption doesn't turn rebuild into an OOM. See `skippedTruncated`
+     * to tell whether the cap was hit. Empty when `skipped === 0`.
+     */
+    skippedIds: readonly string[];
+    /** True when `skipped > skippedIds.length` (the cap was reached). */
+    skippedTruncated: boolean;
+}>;
+
+/**
+ * Store-level search helpers.
+ *
+ * `fulltextSearch` is a thin typed wrapper over `backend.fulltextSearch`.
+ * `hybridSearch` runs a vector and a fulltext query in parallel and
+ * fuses the two ranked lists with Reciprocal Rank Fusion. RRF is
+ * rank-based, so it papers over score-scale differences between
+ * pgvector/sqlite-vec (distance-derived) and tsvector/FTS5 (BM25-style).
+ */
+
+/**
+ * A fulltext search hit. `N` defaults to the generic `Node`; the
+ * `store.search.fulltext<K>(kind)` facade narrows it to the concrete
+ * typed node for that kind so callers get `hit.node.title` without a cast.
+ */
+type FulltextSearchHit<N = Node> = Readonly<{
+    node: N;
+    /** Backend-native relevance score; higher is better. */
+    score: number;
+    /** 1-based rank within the result set. */
+    rank: number;
+    /** Highlighted snippet (only present when `includeSnippets: true`). */
+    snippet?: string;
+}>;
+type VectorSearchHit<N = Node> = Readonly<{
+    node: N;
+    score: number;
+    rank: number;
+}>;
+/**
+ * A hybrid search hit. Both sub-results (`vector`, `fulltext`) carry the
+ * same narrowed node type as the top-level `node` for ergonomic access.
+ */
+type HybridSearchHit<N = Node> = Readonly<{
+    node: N;
+    /** Fused RRF score (higher is better). */
+    score: number;
+    /** 1-based rank in the fused list. */
+    rank: number;
+    /** Sub-result from the vector half, if it ranked this node. */
+    vector?: VectorSearchHit<N>;
+    /** Sub-result from the fulltext half, if it ranked this node. */
+    fulltext?: FulltextSearchHit<N>;
+}>;
+type FulltextSearchOptions = Readonly<{
+    /** The user-supplied query string. */
+    query: string;
+    /** Max results. Required. */
+    limit: number;
+    /** Query parser mode. Default: "websearch". */
+    mode?: FulltextQueryMode;
+    /**
+     * Language override for query parsing. Default: per-row language as
+     * stored at insert time.
+     */
+    language?: string;
+    /** Minimum relevance score to include in results. */
+    minScore?: number;
+    /** Return a highlighted snippet alongside each hit. */
+    includeSnippets?: boolean;
+}>;
+type HybridVectorOptions = Readonly<{
+    /** Field path of the embedding column on the node kind. */
+    fieldPath: string;
+    /** Query embedding to compare against. */
+    queryEmbedding: readonly number[];
+    /** Distance metric. Default: "cosine". */
+    metric?: VectorMetric;
+    /** How many candidates to retrieve from the vector side. Default: 4 * limit. */
+    k?: number;
+    /** Minimum similarity to include (units depend on metric). */
+    minScore?: number;
+}>;
+type HybridFulltextOptions = Readonly<{
+    query: string;
+    /** How many candidates to retrieve from the fulltext side. Default: 4 * limit. */
+    k?: number;
+    mode?: FulltextQueryMode;
+    language?: string;
+    minScore?: number;
+    includeSnippets?: boolean;
+}>;
+type HybridSearchOptions = Readonly<{
+    vector: HybridVectorOptions;
+    fulltext: HybridFulltextOptions;
+    fusion?: HybridFusionOptions;
+    /** Final number of fused results to return. Required. */
+    limit: number;
+}>;
+
+/**
+ * StoreSearch — store.search facade.
+ *
+ * Groups fulltext, hybrid, and maintenance operations under one
+ * namespace so the top-level Store API stays focused on CRUD + graph
+ * traversal. The three methods delegate to their respective execution
+ * modules; this class exists purely to shape the surface, not to add
+ * behavior.
+ */
+
+/**
+ * Narrows `Node` to the concrete typed node for a given kind in the graph.
+ */
+type NodeOfKind<G extends GraphDef, K extends NodeKinds<G>> = G["nodes"][K] extends NodeRegistration<infer N extends NodeType> ? Node<N> : Node;
+type StoreSearchContext = Readonly<{
+    graphId: string;
+    backend: GraphBackend;
+    registry: KindRegistry;
+}>;
+/**
+ * Search-related operations exposed via `store.search`.
+ *
+ * @example
+ * ```typescript
+ * // Fulltext only
+ * const hits = await store.search.fulltext("Document", {
+ *   query: "climate change",
+ *   limit: 10,
+ *   includeSnippets: true,
+ * });
+ *
+ * // Hybrid: vector + fulltext, fused with RRF
+ * const ranked = await store.search.hybrid("Document", {
+ *   limit: 10,
+ *   vector: { fieldPath: "embedding", queryEmbedding: vec },
+ *   fulltext: { query: "climate change" },
+ * });
+ *
+ * // Rebuild after backfill / schema change
+ * const stats = await store.search.rebuildFulltext();
+ * ```
+ */
+declare class StoreSearch<G extends GraphDef> {
+    #private;
+    constructor(context: StoreSearchContext);
+    /**
+     * Runs a fulltext search against nodes of the given kind.
+     *
+     * Requires fields on the node schema declared with `searchable()`.
+     * The search hits the backend's fulltext index (tsvector + GIN on
+     * Postgres, FTS5 on SQLite — or whatever strategy the backend is
+     * configured with) and resolves the matching node IDs back to typed
+     * `Node` objects.
+     */
+    fulltext<K extends NodeKinds<G>>(nodeKind: K, options: FulltextSearchOptions): Promise<readonly FulltextSearchHit<NodeOfKind<G, K>>[]>;
+    /**
+     * Runs a vector + fulltext hybrid search and fuses the results with
+     * Reciprocal Rank Fusion.
+     *
+     * RRF is rank-based, so it composes well across heterogeneous score
+     * scales (cosine similarity vs ts_rank_cd vs FTS5 BM25). Default
+     * over-fetch is 4× `limit` from each source — tune via `vector.k` /
+     * `fulltext.k` for higher-recall corpora.
+     */
+    hybrid<K extends NodeKinds<G>>(nodeKind: K, options: HybridSearchOptions): Promise<readonly HybridSearchHit<NodeOfKind<G, K>>[]>;
+    /**
+     * Rebuilds the fulltext index from existing node data.
+     *
+     * Use when:
+     * - A node kind gained a `searchable()` field after data was already
+     *   written and existing rows were never indexed.
+     * - The fulltext table was dropped / truncated.
+     * - `language` was changed on a `searchable()` field.
+     *
+     * Iterates nodes with keyset pagination (stable under shared
+     * timestamps and light concurrent writes), transacts per page, skips
+     * kinds with no searchable fields, and cleans up stale rows for
+     * soft-deleted nodes. Corrupt or non-object `props` are counted in
+     * `skipped` with their node IDs surfaced via `skippedIds` so operators
+     * can investigate. Concurrent hard-deletes between page fetches can
+     * be missed by a single pass — run during a maintenance window for
+     * full consistency.
+     */
+    rebuildFulltext<K extends NodeKinds<G>>(nodeKind?: K, options?: RebuildFulltextOptions): Promise<RebuildFulltextResult>;
+}
+
 /**
  * Main Store implementation for TypeGraph.
  *
@@ -2161,6 +2731,27 @@ declare class Store<G extends GraphDef> {
      * ```
      */
     get edges(): GraphEdgeCollections<G>;
+    /**
+     * Tier 1 graph algorithms: shortest path, reachability, neighborhoods, and
+     * degree centrality.
+     *
+     * Each call compiles to a single recursive-CTE query against the backend.
+     * The facade is built lazily on first access and cached for the lifetime
+     * of the store.
+     *
+     * @example
+     * ```typescript
+     * const path = await store.algorithms.shortestPath(alice, bob, {
+     *   edges: ["knows"],
+     * });
+     *
+     * const friends = await store.algorithms.neighbors(alice, {
+     *   edges: ["knows"],
+     *   depth: 2,
+     * });
+     * ```
+     */
+    get algorithms(): GraphAlgorithms<G>;
     /**
      * Returns the node collection for the given kind, or undefined if the kind
      * is not registered in this graph.
@@ -2191,6 +2782,34 @@ declare class Store<G extends GraphDef> {
      * ```
      */
     query(): QueryBuilder<G>;
+    /**
+     * Search-related operations (fulltext, hybrid, and rebuild).
+     *
+     * All search methods live under this facade to keep the top-level
+     * Store API focused on CRUD + graph traversal. The facade is
+     * lazy-initialized and cached for the lifetime of the store.
+     *
+     * @example
+     * ```typescript
+     * // Fulltext
+     * const hits = await store.search.fulltext("Document", {
+     *   query: "climate warming",
+     *   limit: 10,
+     *   includeSnippets: true,
+     * });
+     *
+     * // Hybrid (vector + fulltext fused with RRF)
+     * const ranked = await store.search.hybrid("Document", {
+     *   limit: 10,
+     *   vector: { fieldPath: "embedding", queryEmbedding: vec },
+     *   fulltext: { query: "climate warming" },
+     * });
+     *
+     * // Rebuild index after schema change
+     * const stats = await store.search.rebuildFulltext();
+     * ```
+     */
+    get search(): StoreSearch<G>;
     /**
      * Executes multiple queries over a single connection with snapshot consistency.
      *
@@ -2354,4 +2973,4 @@ 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]>;
 
-export { type StoreProjection as $, type AliasMap as A, type BatchResults as B, type CreateQueryBuilderOptions as C, type DynamicEdgeCollection as D, type EdgeAliasMap as E, type FieldAccessor as F, type GetOrCreateAction as G, type HookContext as H, type IfExistsMode as I, type PaginatedResult as J, type Predicate as K, PreparedQuery as L, type PropsAccessor as M, type Node as N, type OperationHookContext as O, type PaginateOptions as P, QueryBuilder as Q, type QueryHookContext as R, type QueryOptions as S, TraversalBuilder as T, type RecursiveTraversalOptions as U, type SelectContext as V, type SelectableEdge as W, type SelectableNode as X, Store as Y, type StoreHooks as Z, type StoreOptions as _, type AggregateResult as a, type StreamOptions as a0, type SubgraphEdgeResult as a1, type SubgraphNodeResult as a2, type SubgraphOptions as a3, type SubgraphResult as a4, type SubsetEdge as a5, type SubsetNode as a6, type TransactionContext as a7, type TypedEdgeCollection as a8, UnionableQuery as a9, type UpdateEdgeInput as aa, type UpdateNodeInput as ab, createStore as ac, createStoreWithSchema as ad, defineSubgraphProject as ae, embedding as af, exists as ag, fieldRef as ah, getEmbeddingDimensions as ai, inSubquery as aj, isEmbeddingSchema as ak, isParameterRef as al, notExists as am, notInSubquery as an, param as ao, type AnyEdge as b, type AnyNode as c, type BatchableQuery as d, type ConstraintNames as e, type CreateEdgeInput as f, type CreateNodeInput as g, type DynamicNodeCollection as h, type Edge as i, type EdgeAccessor as j, type EdgeCollection as k, type EdgeFindByEndpointsOptions as l, type EdgeGetOrCreateByEndpointsOptions as m, type EdgeGetOrCreateByEndpointsResult as n, type EmbeddingSchema as o, type EmbeddingValue as p, ExecutableAggregateQuery as q, ExecutableQuery as r, type GraphEdgeCollections as s, type GraphNodeCollections as t, type NodeAccessor as u, type NodeAlias as v, type NodeCollection as w, type NodeGetOrCreateByConstraintOptions as x, type NodeGetOrCreateByConstraintResult as y, type NodeRef as z };
+export { type PaginatedResult as $, type AliasMap as A, type BaseTraversalOptions as B, type CreateQueryBuilderOptions as C, DEFAULT_SEARCHABLE_LANGUAGE as D, type EdgeAliasMap as E, type FieldAccessor as F, type GetOrCreateAction as G, type GraphNodeCollections as H, type HookContext as I, type HybridFulltextOptions as J, type HybridSearchHit as K, type HybridSearchOptions as L, type HybridVectorOptions as M, type IfExistsMode as N, type NeighborsOptions as O, type Node as P, QueryBuilder as Q, type NodeAccessor as R, type NodeAlias as S, TraversalBuilder as T, type NodeCollection as U, type NodeGetOrCreateByConstraintOptions as V, type NodeGetOrCreateByConstraintResult as W, type NodeIdentifier as X, type NodeRef as Y, type OperationHookContext as Z, type PaginateOptions as _, type AggregateResult as a, type PathNode as a0, type Predicate as a1, PreparedQuery as a2, type PropsAccessor as a3, type QueryHookContext as a4, type QueryOptions as a5, type ReachableNode as a6, type ReachableOptions as a7, type RebuildFulltextOptions as a8, type RebuildFulltextResult as a9, type UpdateEdgeInput as aA, type UpdateNodeInput as aB, type VectorSearchHit as aC, createStore as aD, createStoreWithSchema as aE, defineSubgraphProject as aF, embedding as aG, exists as aH, fieldRef as aI, getEmbeddingDimensions as aJ, getSearchableMetadata as aK, inSubquery as aL, isEmbeddingSchema as aM, isParameterRef as aN, isSearchableSchema as aO, notExists as aP, notInSubquery as aQ, param as aR, searchable as aS, type RecursiveTraversalOptions as aa, type SearchableMetadata as ab, type SearchableOptions as ac, type SearchableSchema as ad, type SelectContext as ae, type SelectableEdge as af, type SelectableNode as ag, type ShortestPathOptions as ah, type ShortestPathResult as ai, Store as aj, type StoreHooks as ak, type StoreOptions as al, type StoreProjection as am, StoreSearch as an, type StreamOptions as ao, type SubgraphEdgeResult as ap, type SubgraphNodeResult as aq, type SubgraphOptions as ar, type SubgraphResult as as, type SubsetEdge as at, type SubsetNode as au, type TemporalAlgorithmOptions as av, type TransactionContext as aw, type TraversalDirection as ax, type TypedEdgeCollection as ay, UnionableQuery as az, type AlgorithmCyclePolicy as b, 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 DynamicEdgeCollection as k, type DynamicNodeCollection as l, type Edge as m, type EdgeAccessor as n, type EdgeCollection as o, type EdgeFindByEndpointsOptions as p, type EdgeGetOrCreateByEndpointsOptions as q, type EdgeGetOrCreateByEndpointsResult as r, type EmbeddingSchema as s, type EmbeddingValue as t, ExecutableAggregateQuery as u, ExecutableQuery as v, type FulltextSearchHit as w, type FulltextSearchOptions as x, type GraphAlgorithms as y, type GraphEdgeCollections as z };