@nicia-ai/typegraph 0.20.0 → 0.21.0

package/dist/index.js

@@ -1,12 +1,13 @@
-import { META_EDGE_BRAND, META_EDGE_SUB_CLASS_OF, META_EDGE_NARROWER, META_EDGE_BROADER, META_EDGE_RELATED_TO, META_EDGE_EQUIVALENT_TO, META_EDGE_SAME_AS, META_EDGE_DIFFERENT_FROM, META_EDGE_DISJOINT_WITH, META_EDGE_HAS_PART, META_EDGE_PART_OF, META_EDGE_INVERSE_OF, META_EDGE_IMPLIES, ensureSchema, computeClosuresFromOntology, createEmptyClosures, KindRegistry, validateNodeProps, validateEdgeProps } from './chunk-W6M7XWKX.js';
-export { isMetaEdge } from './chunk-W6M7XWKX.js';
-import { NODE_TYPE_BRAND, EDGE_TYPE_BRAND, nowIso, validateOptionalIsoDate, getNodeKinds, getEdgeKinds } from './chunk-G5CYWKRF.js';
-export { defineGraph, getEdgeKinds, getNodeKinds, isEdgeType, isEdgeTypeWithEndpoints, isGraphDef, isNodeType } from './chunk-G5CYWKRF.js';
+import { META_EDGE_BRAND, META_EDGE_SUB_CLASS_OF, META_EDGE_NARROWER, META_EDGE_BROADER, META_EDGE_RELATED_TO, META_EDGE_EQUIVALENT_TO, META_EDGE_SAME_AS, META_EDGE_DIFFERENT_FROM, META_EDGE_DISJOINT_WITH, META_EDGE_HAS_PART, META_EDGE_PART_OF, META_EDGE_INVERSE_OF, META_EDGE_IMPLIES, ensureSchema, computeClosuresFromOntology, createEmptyClosures, KindRegistry, validateNodeProps, validateEdgeProps } from './chunk-JYUQA77I.js';
+export { isMetaEdge } from './chunk-JYUQA77I.js';
+import { NODE_TYPE_BRAND, EDGE_TYPE_BRAND, nowIso, validateOptionalIsoDate, getNodeKinds, getEdgeKinds } from './chunk-RS5OLGEW.js';
+export { defineGraph, getEdgeKinds, getNodeKinds, isEdgeType, isEdgeTypeWithEndpoints, isGraphDef, isNodeType } from './chunk-RS5OLGEW.js';
 import { ConfigurationError, UnsupportedPredicateError, ValidationError, CompilerInvariantError, KindNotFoundError, DatabaseOperationError, EdgeNotFoundError, NodeConstraintNotFoundError, RestrictedDeleteError, NodeNotFoundError, EndpointNotFoundError, UniquenessError, CardinalityError, EndpointError, DisjointError } from './chunk-WFMTAEEN.js';
 export { BackendDisposedError, CardinalityError, CompilerInvariantError, ConfigurationError, DatabaseOperationError, DisjointError, EdgeNotFoundError, EndpointError, EndpointNotFoundError, KindNotFoundError, MigrationError, NodeConstraintNotFoundError, NodeNotFoundError, RestrictedDeleteError, SchemaMismatchError, TypeGraphError, UniquenessError, UnsupportedPredicateError, ValidationError, VersionConflictError, getErrorSuggestion, isConstraintError, isSystemError, isTypeGraphError, isUserRecoverable } from './chunk-WFMTAEEN.js';
-import { MAX_PG_IDENTIFIER_LENGTH, DEFAULT_PAGINATION_LIMIT, getDialect, DEFAULT_STREAM_BATCH_SIZE, NODE_META_KEYS, EDGE_META_KEYS, SQLITE_PATH_DELIMITER, PG_ARRAY_START, PG_ARRAY_END, PG_PATH_ELEMENT_SEPARATOR, fnv1aBase36 } from './chunk-GNIYZKBI.js';
-import { jsonPointer, parseJsonPointer, createSchemaIntrospector, normalizeJsonPointer, joinJsonPointers, resolveFieldTypeInfoAtJsonPointer, getEmbeddingDimensions, isEmbeddingSchema } from './chunk-K7SQ3SWP.js';
-export { MAX_JSON_POINTER_DEPTH, embedding, getEmbeddingDimensions, isEmbeddingSchema, joinJsonPointers, jsonPointer, normalizeJsonPointer, parseJsonPointer } from './chunk-K7SQ3SWP.js';
+import { MAX_PG_IDENTIFIER_LENGTH, DEFAULT_PAGINATION_LIMIT, getDialect, DEFAULT_STREAM_BATCH_SIZE, NODE_META_KEYS, EDGE_META_KEYS, SQLITE_PATH_DELIMITER, PG_ARRAY_START, PG_ARRAY_END, PG_PATH_ELEMENT_SEPARATOR, fnv1aBase36 } from './chunk-4XNE2JG3.js';
+export { fts5Strategy, tsvectorStrategy } from './chunk-4XNE2JG3.js';
+import { jsonPointer, parseJsonPointer, createSchemaIntrospector, normalizeJsonPointer, joinJsonPointers, resolveFieldTypeInfoAtJsonPointer, getSearchableMetadata, DEFAULT_SEARCHABLE_LANGUAGE, getEmbeddingDimensions, isEmbeddingSchema } from './chunk-EYELZHKY.js';
+export { DEFAULT_SEARCHABLE_LANGUAGE, MAX_JSON_POINTER_DEPTH, embedding, getEmbeddingDimensions, getSearchableMetadata, isEmbeddingSchema, isSearchableSchema, joinJsonPointers, jsonPointer, normalizeJsonPointer, parseJsonPointer, searchable } from './chunk-EYELZHKY.js';
 import { z } from 'zod';
 import { sql, Placeholder } from 'drizzle-orm';
 import { nanoid } from 'nanoid';
@@ -31,6 +32,44 @@ var PROTOTYPE_POLLUTION_KEYS = /* @__PURE__ */ new Set([
   "constructor",
   "prototype"
 ]);
+var RESERVED_PROPERTY_PREFIX = "$";
+function isReservedPropertyName(name) {
+  return name.startsWith(RESERVED_PROPERTY_PREFIX);
+}
+function assertSchemaKeysAreFree(entityKind, name, keys, reservedStructuralKeys) {
+  const structuralConflicts = keys.filter(
+    (key) => reservedStructuralKeys.has(key)
+  );
+  if (structuralConflicts.length > 0) {
+    const label = entityKind.toLowerCase();
+    throw new ConfigurationError(
+      `${entityKind} "${name}" schema contains reserved property names: ${structuralConflicts.join(", ")}`,
+      {
+        [`${label}Type`]: name,
+        conflicts: structuralConflicts,
+        reservedKeys: [...reservedStructuralKeys]
+      },
+      {
+        suggestion: `Rename the conflicting properties. Reserved names (${[...reservedStructuralKeys].join(", ")}) are added automatically to all ${label}s.`
+      }
+    );
+  }
+  const prefixConflicts = keys.filter((key) => isReservedPropertyName(key));
+  if (prefixConflicts.length > 0) {
+    const label = entityKind.toLowerCase();
+    throw new ConfigurationError(
+      `${entityKind} "${name}" schema uses the reserved "${RESERVED_PROPERTY_PREFIX}" prefix on: ${prefixConflicts.join(", ")}`,
+      {
+        [`${label}Type`]: name,
+        conflicts: prefixConflicts,
+        reservedPrefix: RESERVED_PROPERTY_PREFIX
+      },
+      {
+        suggestion: `Property names starting with "${RESERVED_PROPERTY_PREFIX}" are reserved for TypeGraph accessors (e.g. $fulltext). Rename each field.`
+      }
+    );
+  }
+}
 function validateProjectionField(field2, entityType, kind) {
   const reserved = entityType === "node" ? RESERVED_NODE_KEYS : RESERVED_EDGE_KEYS;
   if (reserved.has(field2)) {
@@ -64,19 +103,12 @@ function filterReservedKeys(props, reservedKeys) {
 
 // src/core/node.ts
 function validateSchemaKeys(schema, name) {
-  const shape = schema.shape;
-  const conflicts = Object.keys(shape).filter(
-    (key) => RESERVED_NODE_KEYS.has(key)
+  assertSchemaKeysAreFree(
+    "Node",
+    name,
+    Object.keys(schema.shape),
+    RESERVED_NODE_KEYS
   );
-  if (conflicts.length > 0) {
-    throw new ConfigurationError(
-      `Node "${name}" schema contains reserved property names: ${conflicts.join(", ")}`,
-      { nodeType: name, conflicts, reservedKeys: [...RESERVED_NODE_KEYS] },
-      {
-        suggestion: `Rename the conflicting properties. Reserved names (id, kind, meta) are added automatically to all nodes.`
-      }
-    );
-  }
 }
 function defineNode(name, options) {
   validateSchemaKeys(options.schema, name);
@@ -89,19 +121,12 @@ function defineNode(name, options) {
 }
 var EMPTY_SCHEMA = z.object({});
 function validateSchemaKeys2(schema, name) {
-  const shape = schema.shape;
-  const conflicts = Object.keys(shape).filter(
-    (key) => RESERVED_EDGE_KEYS.has(key)
+  assertSchemaKeysAreFree(
+    "Edge",
+    name,
+    Object.keys(schema.shape),
+    RESERVED_EDGE_KEYS
   );
-  if (conflicts.length > 0) {
-    throw new ConfigurationError(
-      `Edge "${name}" schema contains reserved property names: ${conflicts.join(", ")}`,
-      { edgeType: name, conflicts, reservedKeys: [...RESERVED_EDGE_KEYS] },
-      {
-        suggestion: `Rename the conflicting properties. Reserved names are added automatically to all edges.`
-      }
-    );
-  }
 }
 function defineEdge(name, options) {
   const schema = options?.schema ?? EMPTY_SCHEMA;
@@ -567,6 +592,41 @@ function stringField(field2) {
     ilike: (pattern) => stringOp("ilike", field2, pattern)
   };
 }
+var DEFAULT_FULLTEXT_MATCH_K = 50;
+function createFulltextAccessor(alias, hasSearchableField) {
+  return {
+    matches: (query, k, options) => {
+      if (!hasSearchableField()) {
+        throw new UnsupportedPredicateError(
+          `Cannot call .$fulltext.matches() on alias "${alias}" \u2014 its node kind has no fields declared with searchable(). Add at least one: \`title: searchable({ language: "english" })\`.`
+        );
+      }
+      return fulltextMatch(
+        fieldRef(alias, ["$fulltext"]),
+        query,
+        k ?? DEFAULT_FULLTEXT_MATCH_K,
+        options
+      );
+    }
+  };
+}
+function fulltextMatch(field2, query, limit, options) {
+  if (!Number.isFinite(limit) || limit <= 0) {
+    throw new UnsupportedPredicateError(
+      `matches() limit must be a positive finite number, got ${String(limit)}`
+    );
+  }
+  const expr = {
+    __type: "fulltext_match",
+    field: field2,
+    query,
+    mode: options?.mode ?? "websearch",
+    limit,
+    ...options?.language === void 0 ? {} : { language: options.language },
+    ...options?.minScore === void 0 ? {} : { minScore: options.minScore }
+  };
+  return predicate(expr);
+}
 function numberField(field2) {
   return {
     ...baseFieldBuilder(field2),
@@ -1142,11 +1202,13 @@ function compilePredicateExpression(expr, ctx) {
     case "in_subquery": {
       return compileInSubquery(expr, ctx);
     }
-    case "vector_similarity": {
-      return compileVectorSimilarityPredicate();
+    case "vector_similarity":
+    case "fulltext_match": {
+      return STRUCTURAL_PREDICATE_NOOP;
     }
   }
 }
+var STRUCTURAL_PREDICATE_NOOP = sql.raw("1=1");
 function compileComparisonPredicate(expr, dialect, cteColumnPrefix) {
   if (isParameterRef(expr.right)) {
     const parameterValueType = normalizeValueType2(expr.right.valueType) ?? normalizeValueType2(expr.left.valueType);
@@ -1400,45 +1462,61 @@ function compileInSubquery(expr, ctx) {
   const subSql = ctx.compileQuery(expr.subquery, expr.subquery.graphId);
   return expr.negated ? sql`${fieldSql} NOT IN (${subSql})` : sql`${fieldSql} IN (${subSql})`;
 }
-function compileVectorSimilarityPredicate(_expr, _ctx) {
-  return sql.raw("1=1");
-}
-function extractVectorSimilarityPredicates(predicates) {
+function extractStructuralPredicates(predicates, isMatch, rejectionMessage) {
   const results = [];
   function visit(expr, inDisallowedBranch) {
-    switch (expr.__type) {
-      case "vector_similarity": {
-        if (inDisallowedBranch) {
-          throw new UnsupportedPredicateError(
-            "Vector similarity predicates cannot be nested under OR or NOT. Use top-level AND combinations instead."
-          );
-        }
-        results.push(expr);
-        break;
+    if (isMatch(expr)) {
+      if (inDisallowedBranch) {
+        throw new UnsupportedPredicateError(rejectionMessage);
       }
+      results.push(expr);
+      return;
+    }
+    switch (expr.__type) {
       case "and": {
-        for (const predicate2 of expr.predicates) {
-          visit(predicate2, inDisallowedBranch);
-        }
-        break;
+        for (const child of expr.predicates) visit(child, inDisallowedBranch);
+        return;
       }
       case "or": {
-        for (const predicate2 of expr.predicates) {
-          visit(predicate2, true);
-        }
-        break;
+        for (const child of expr.predicates) visit(child, true);
+        return;
       }
       case "not": {
         visit(expr.predicate, true);
-        break;
+        return;
+      }
+      case "comparison":
+      case "string_op":
+      case "null_check":
+      case "between":
+      case "array_op":
+      case "object_op":
+      case "aggregate_comparison":
+      case "exists":
+      case "in_subquery":
+      case "vector_similarity":
+      case "fulltext_match": {
+        return;
       }
     }
   }
-  for (const pred of predicates) {
-    visit(pred.expression, false);
-  }
+  for (const pred of predicates) visit(pred.expression, false);
   return results;
 }
+function extractVectorSimilarityPredicates(predicates) {
+  return extractStructuralPredicates(
+    predicates,
+    (expr) => expr.__type === "vector_similarity",
+    "Vector similarity predicates cannot be nested under OR or NOT. Use top-level AND combinations instead."
+  );
+}
+function extractFulltextMatchPredicates(predicates) {
+  return extractStructuralPredicates(
+    predicates,
+    (expr) => expr.__type === "fulltext_match",
+    "Fulltext match predicates cannot be nested under OR or NOT. Use top-level AND combinations instead."
+  );
+}
 
 // src/query/compiler/predicate-utils.ts
 var EMPTY_PREDICATES = [];
@@ -1497,6 +1575,10 @@ function getNodeKindsForAlias(ast, alias) {
   }
   throw new CompilerInvariantError(`Unknown traversal source alias: ${alias}`);
 }
+function getHybridTargetAlias(vectorPredicate, fulltextPredicate) {
+  if (!vectorPredicate || !fulltextPredicate) return void 0;
+  return vectorPredicate.field.alias === fulltextPredicate.field.alias ? vectorPredicate.field.alias : void 0;
+}
 
 // src/query/compiler/emitter/plan-inspector.ts
 function collectPlanOperations(node, ops) {
@@ -1504,6 +1586,7 @@ function collectPlanOperations(node, ops) {
   switch (node.op) {
     case "aggregate":
     case "filter":
+    case "fulltext_match":
     case "join":
     case "limit_offset":
     case "project":
@@ -1532,6 +1615,7 @@ function findUnaryNodeInProjectChain(rootNode, op) {
     switch (currentNode.op) {
       case "aggregate":
       case "filter":
+      case "fulltext_match":
       case "join":
       case "limit_offset":
       case "recursive_expand":
@@ -1567,6 +1651,7 @@ function inspectProjectPlan(logicalPlan) {
   );
   return {
     hasAggregate: operations.has("aggregate"),
+    hasFulltextMatch: operations.has("fulltext_match"),
     hasLimitOffset: operations.has("limit_offset"),
     hasRecursiveExpand: operations.has("recursive_expand"),
     hasSetOperation: operations.has("set_op"),
@@ -1618,6 +1703,7 @@ function findTopLevelLimitOffsetNode(rootNode) {
     switch (currentNode.op) {
       case "aggregate":
       case "filter":
+      case "fulltext_match":
       case "join":
       case "project":
       case "recursive_expand":
@@ -1642,6 +1728,7 @@ function findTopLevelSortNode(rootNode) {
     switch (currentNode.op) {
       case "aggregate":
       case "filter":
+      case "fulltext_match":
       case "join":
       case "limit_offset":
       case "project":
@@ -1776,16 +1863,16 @@ function assertStandardEmitterClauseAlignment(logicalPlan, input) {
       { component: "standard-emitter" }
     );
   }
-  const expectsOrderBy = planShape.hasSort || planShape.hasVectorKnn;
+  const expectsOrderBy = planShape.hasSort || planShape.hasVectorKnn || planShape.hasFulltextMatch;
   if (expectsOrderBy && input.orderBy === void 0) {
     throw new CompilerInvariantError(
-      "Standard SQL emitter expected ORDER BY clause for plan containing a sort or vector_knn node",
+      "Standard SQL emitter expected ORDER BY clause for plan containing a sort, vector_knn, or fulltext_match node",
       { component: "standard-emitter" }
     );
   }
   if (!expectsOrderBy && input.orderBy !== void 0) {
     throw new CompilerInvariantError(
-      "Standard SQL emitter received ORDER BY clause for a plan without sort or vector_knn nodes",
+      "Standard SQL emitter received ORDER BY clause for a plan without sort, vector_knn, or fulltext_match nodes",
       { component: "standard-emitter" }
     );
   }
@@ -1824,6 +1911,62 @@ function emitStandardQuerySql(input) {
   return sql.join(parts, sql` `);
 }
 
+// src/query/ast.ts
+var DEFAULT_RRF_K = 60;
+var DEFAULT_RRF_WEIGHT = 1;
+function mergeEdgeKinds(traversal) {
+  const inverse = traversal.inverseEdgeKinds;
+  if (inverse === void 0 || inverse.length === 0) return traversal.edgeKinds;
+  return [
+    ...traversal.edgeKinds,
+    ...inverse.filter((kind) => !traversal.edgeKinds.includes(kind))
+  ];
+}
+var DEFAULT_TABLE_NAMES = {
+  nodes: "typegraph_nodes",
+  edges: "typegraph_edges",
+  embeddings: "typegraph_node_embeddings",
+  fulltext: "typegraph_node_fulltext"
+};
+var VALID_IDENTIFIER_PATTERN = /^[a-z_][a-z0-9_$]*$/i;
+function validateTableName(name, label) {
+  if (!name || name.length === 0) {
+    throw new ConfigurationError(`${label} table name cannot be empty`);
+  }
+  if (name.length > MAX_PG_IDENTIFIER_LENGTH) {
+    throw new ConfigurationError(
+      `${label} table name exceeds maximum length of ${MAX_PG_IDENTIFIER_LENGTH} characters`
+    );
+  }
+  if (!VALID_IDENTIFIER_PATTERN.test(name)) {
+    throw new ConfigurationError(
+      `${label} table name "${name}" is not a valid SQL identifier. Table names must start with a letter or underscore and contain only letters, digits, underscores, or dollar signs.`
+    );
+  }
+}
+function quoteIdentifier(name) {
+  return `"${name.replaceAll('"', '""')}"`;
+}
+function createSqlSchema(names = {}) {
+  const tables = { ...DEFAULT_TABLE_NAMES, ...names };
+  validateTableName(tables.nodes, "nodes");
+  validateTableName(tables.edges, "edges");
+  validateTableName(tables.embeddings, "embeddings");
+  validateTableName(tables.fulltext, "fulltext");
+  return {
+    tables,
+    nodesTable: sql.raw(quoteIdentifier(tables.nodes)),
+    edgesTable: sql.raw(quoteIdentifier(tables.edges)),
+    embeddingsTable: sql.raw(quoteIdentifier(tables.embeddings)),
+    fulltextTable: sql.raw(quoteIdentifier(tables.fulltext))
+  };
+}
+var DEFAULT_SQL_SCHEMA = createSqlSchema();
+var ALIAS_CTE_PREFIX = "cte_";
+var EMBEDDINGS_CTE_ALIAS = "cte_embeddings";
+var FULLTEXT_CTE_ALIAS = "cte_fulltext";
+var HYBRID_CANDIDATES_CTE_ALIAS = "cte_relevance_candidates";
+
 // src/query/compiler/typed-json-extract.ts
 function compileTypedJsonExtract(input) {
   const { column, dialect, pointer, valueType } = input;
@@ -1877,7 +2020,7 @@ var EDGE_COLUMNS = [
   "deleted_at"
 ];
 var EMPTY_REQUIRED_COLUMNS = /* @__PURE__ */ new Set();
-function quoteIdentifier(identifier) {
+function quoteIdentifier2(identifier) {
   return sql.raw(`"${identifier.replaceAll('"', '""')}"`);
 }
 function shouldProjectColumn(requiredColumns, column, alwaysRequiredColumns) {
@@ -1931,6 +2074,21 @@ function compileColumnReference(tableAlias, column) {
   }
   return sql`${sql.raw(tableAlias)}.${sql.raw(column)}`;
 }
+function qualifyColumn(owner, name) {
+  return sql`${quoteIdentifier2(owner)}.${quoteIdentifier2(name)}`;
+}
+var SCOPED_RELEVANCE_NODES_ALIAS = "scoped_relevance_nodes";
+function buildScopedNodeIdsSubquery(nodeAlias) {
+  const cteAlias = `${ALIAS_CTE_PREFIX}${nodeAlias}`;
+  return sql`
+    (
+        SELECT DISTINCT
+          ${qualifyColumn(cteAlias, `${nodeAlias}_id`)} AS node_id,
+          ${qualifyColumn(cteAlias, `${nodeAlias}_kind`)} AS node_kind
+        FROM ${quoteIdentifier2(cteAlias)}
+      ) AS ${sql.raw(SCOPED_RELEVANCE_NODES_ALIAS)}
+  `;
+}
 function compileNodeSelectColumns(tableAlias, alias, requiredColumns) {
   return NODE_COLUMNS.filter(
     (column) => column === "id" || column === "kind" || shouldProjectColumn(requiredColumns, column)
@@ -2183,7 +2341,7 @@ function buildStandardProjection(input) {
   }
   const projectedFields = fields.map((field2) => {
     const source = compileProjectedSource(field2, dialect);
-    return sql`${source} AS ${quoteIdentifier(field2.outputName)}`;
+    return sql`${source} AS ${quoteIdentifier2(field2.outputName)}`;
   });
   return sql.join(projectedFields, sql`, `);
 }
@@ -2203,7 +2361,7 @@ function compileSelectiveProjection(fields, dialect, ast, collapsedTraversalCteA
     const cteAlias = collapsedTraversalCteAlias ?? aliasToCte.get(field2.alias) ?? `cte_${field2.alias}`;
     if (field2.isSystemField) {
       const dbColumn = mapSelectiveSystemFieldToColumn(field2.field);
-      return sql`${sql.raw(cteAlias)}.${sql.raw(`${field2.alias}_${dbColumn}`)} AS ${quoteIdentifier(field2.outputName)}`;
+      return sql`${sql.raw(cteAlias)}.${sql.raw(`${field2.alias}_${dbColumn}`)} AS ${quoteIdentifier2(field2.outputName)}`;
     }
     const propsColumn = `${field2.alias}_props`;
     const column = sql`${sql.raw(cteAlias)}.${sql.raw(propsColumn)}`;
@@ -2214,12 +2372,56 @@ function compileSelectiveProjection(fields, dialect, ast, collapsedTraversalCteA
       pointer,
       valueType: field2.valueType
     });
-    return sql`${extracted} AS ${quoteIdentifier(field2.outputName)}`;
+    return sql`${extracted} AS ${quoteIdentifier2(field2.outputName)}`;
   });
   return sql.join(columns, sql`, `);
 }
+function buildRelevanceJoins(vectorPredicate, fulltextPredicate) {
+  const hybridTargetAlias = getHybridTargetAlias(
+    vectorPredicate,
+    fulltextPredicate
+  );
+  if (hybridTargetAlias !== void 0) {
+    return [
+      buildHybridCandidateJoin(hybridTargetAlias),
+      buildRelevanceJoin(EMBEDDINGS_CTE_ALIAS, hybridTargetAlias, "LEFT JOIN"),
+      buildRelevanceJoin(FULLTEXT_CTE_ALIAS, hybridTargetAlias, "LEFT JOIN")
+    ];
+  }
+  const joins = [];
+  if (vectorPredicate) {
+    joins.push(
+      buildRelevanceJoin(EMBEDDINGS_CTE_ALIAS, vectorPredicate.field.alias)
+    );
+  }
+  if (fulltextPredicate) {
+    joins.push(
+      buildRelevanceJoin(FULLTEXT_CTE_ALIAS, fulltextPredicate.field.alias)
+    );
+  }
+  return joins;
+}
+function buildHybridCandidateJoin(nodeAlias) {
+  const candidateCte = sql.raw(HYBRID_CANDIDATES_CTE_ALIAS);
+  const node = sql.raw(`${ALIAS_CTE_PREFIX}${nodeAlias}`);
+  const idColumn = sql.raw(`${nodeAlias}_id`);
+  const kindColumn = sql.raw(`${nodeAlias}_kind`);
+  return sql`INNER JOIN ${candidateCte} ON ${candidateCte}.node_id = ${node}.${idColumn} AND ${candidateCte}.node_kind = ${node}.${kindColumn}`;
+}
+function buildRelevanceJoin(cteAlias, nodeAlias, joinType = "INNER JOIN") {
+  const cte = sql.raw(cteAlias);
+  const node = sql.raw(`${ALIAS_CTE_PREFIX}${nodeAlias}`);
+  const idColumn = sql.raw(`${nodeAlias}_id`);
+  const kindColumn = sql.raw(`${nodeAlias}_kind`);
+  return sql`${sql.raw(joinType)} ${cte} ON ${cte}.node_id = ${node}.${idColumn} AND ${cte}.node_kind = ${node}.${kindColumn}`;
+}
 function buildStandardFromClause(input) {
-  const { ast, collapsedTraversalCteAlias, vectorPredicate } = input;
+  const {
+    ast,
+    collapsedTraversalCteAlias,
+    fulltextPredicate,
+    vectorPredicate
+  } = input;
   if (collapsedTraversalCteAlias !== void 0) {
     return sql`FROM ${sql.raw(collapsedTraversalCteAlias)}`;
   }
@@ -2234,11 +2436,8 @@ function buildStandardFromClause(input) {
       sql`${sql.raw(joinType)} ${sql.raw(cteAlias)} ON ${sql.raw(cteAlias)}.${sql.raw(previousAlias)}_id = cte_${sql.raw(previousAlias)}.${sql.raw(previousAlias)}_id AND ${sql.raw(cteAlias)}.${sql.raw(previousAlias)}_kind = cte_${sql.raw(previousAlias)}.${sql.raw(previousAlias)}_kind`
     );
   }
-  if (vectorPredicate) {
-    const nodeAlias = vectorPredicate.field.alias;
-    joins.push(
-      sql`INNER JOIN cte_embeddings ON cte_embeddings.node_id = cte_${sql.raw(nodeAlias)}.${sql.raw(nodeAlias)}_id`
-    );
+  for (const join of buildRelevanceJoins(vectorPredicate, fulltextPredicate)) {
+    joins.push(join);
   }
   return joins.length === 0 ? fromClause : sql`${fromClause} ${sql.join(joins, sql` `)}`;
 }
@@ -2277,6 +2476,15 @@ function fieldRefKey(field2) {
   const pointer = field2.jsonPointer ?? "";
   return `${field2.alias}:${field2.path.join(".")}:${pointer}`;
 }
+function resolveEmbeddingFieldPath(field2) {
+  if (field2.jsonPointer !== void 0 && field2.jsonPointer !== "" && field2.jsonPointer !== "/") {
+    return field2.jsonPointer.replace(/^\//u, "").replaceAll("/", ".");
+  }
+  if (field2.path[0] === "props") {
+    return field2.path.slice(1).join(".");
+  }
+  return field2.path.join(".");
+}
 function buildStandardGroupBy(input) {
   const { ast, dialect } = input;
   if (!ast.groupBy || ast.groupBy.fields.length === 0) {
@@ -2323,18 +2531,29 @@ function buildStandardHaving(input) {
   return sql`HAVING ${condition}`;
 }
 function buildStandardEmbeddingsCte(input) {
-  const { ctx, graphId, vectorPredicate } = input;
+  const { ctx, graphId, nodeKinds, vectorPredicate } = input;
   const { dialect } = ctx;
   const { field: field2, metric, minScore, queryEmbedding } = vectorPredicate;
-  const fieldPath = field2.jsonPointer ?? (field2.path.length > 1 && field2.path[0] === "props" ? `/${field2.path.slice(1).join("/")}` : `/${field2.path.join("/")}`);
+  const embeddingsTableName = ctx.schema.tables.embeddings;
+  if (nodeKinds.length === 0) {
+    throw new UnsupportedPredicateError(
+      "Vector predicate must resolve to at least one node kind"
+    );
+  }
+  const fieldPath = resolveEmbeddingFieldPath(field2);
   const distanceExpr = dialect.vectorDistance(
-    sql.raw("embedding"),
+    qualifyColumn(embeddingsTableName, "embedding"),
     queryEmbedding,
     metric
   );
+  const scopedNodes = buildScopedNodeIdsSubquery(field2.alias);
   const conditions = [
-    sql`graph_id = ${graphId}`,
-    sql`field_path = ${fieldPath}`
+    sql`${qualifyColumn(embeddingsTableName, "graph_id")} = ${graphId}`,
+    compileKindFilter(
+      qualifyColumn(embeddingsTableName, "node_kind"),
+      nodeKinds
+    ),
+    sql`${qualifyColumn(embeddingsTableName, "field_path")} = ${fieldPath}`
   ];
   if (minScore !== void 0) {
     conditions.push(
@@ -2343,14 +2562,29 @@ function buildStandardEmbeddingsCte(input) {
   }
   const scoreExpr = compileVectorScoreExpression(distanceExpr, metric);
   return sql`
-    cte_embeddings AS (
+    ${sql.raw(EMBEDDINGS_CTE_ALIAS)} AS (
       SELECT
         node_id,
-        ${distanceExpr} AS distance,
-        ${scoreExpr} AS score
-      FROM ${ctx.schema.embeddingsTable}
-      WHERE ${sql.join(conditions, sql` AND `)}
-      ORDER BY ${distanceExpr} ASC
+        node_kind,
+        distance,
+        score,
+        ROW_NUMBER() OVER (ORDER BY distance ASC) AS ord
+      FROM (
+        SELECT
+          ${qualifyColumn(embeddingsTableName, "node_id")} AS node_id,
+          ${qualifyColumn(embeddingsTableName, "node_kind")} AS node_kind,
+          ${distanceExpr} AS distance,
+          ${scoreExpr} AS score
+        FROM ${ctx.schema.embeddingsTable}
+        INNER JOIN ${scopedNodes}
+          ON ${sql.raw(`${SCOPED_RELEVANCE_NODES_ALIAS}.node_id`)} =
+             ${qualifyColumn(embeddingsTableName, "node_id")}
+         AND ${sql.raw(`${SCOPED_RELEVANCE_NODES_ALIAS}.node_kind`)} =
+             ${qualifyColumn(embeddingsTableName, "node_kind")}
+        WHERE ${sql.join(conditions, sql` AND `)}
+        ORDER BY distance ASC
+        LIMIT ${vectorPredicate.limit}
+      ) AS vec_inner
     )
   `;
 }
@@ -2380,37 +2614,130 @@ function compileVectorMinScoreCondition(distanceExpr, metric, minScore) {
     }
   }
 }
-function buildStandardVectorOrderBy(input) {
-  const { ast, dialect } = input;
-  const distanceOrder = sql`cte_embeddings.distance ASC`;
-  const additionalOrders = [];
-  if (ast.orderBy && ast.orderBy.length > 0) {
-    const aliasToCte = buildAliasToCteMap(ast);
-    for (const orderSpec of ast.orderBy) {
-      const valueType = orderSpec.field.valueType;
-      if (valueType === "array" || valueType === "object") {
-        throw new UnsupportedPredicateError(
-          "Ordering by JSON arrays or objects is not supported"
-        );
-      }
-      const cteAlias = aliasToCte.get(orderSpec.field.alias) ?? `cte_${orderSpec.field.alias}`;
-      const field2 = compileFieldValue(
-        orderSpec.field,
-        dialect,
-        valueType,
-        cteAlias
-      );
-      const direction = sql.raw(orderSpec.direction.toUpperCase());
-      const nulls = orderSpec.nulls ?? (orderSpec.direction === "asc" ? "last" : "first");
-      const nullsDirection = sql.raw(nulls === "first" ? "DESC" : "ASC");
-      additionalOrders.push(
-        sql`(${field2} IS NULL) ${nullsDirection}`,
-        sql`${field2} ${direction}`
+function buildStandardFulltextCte(input) {
+  const { ctx, fulltextPredicate, graphId, nodeKinds } = input;
+  const { dialect, schema } = ctx;
+  const { query, mode, language, limit, minScore } = fulltextPredicate;
+  if (nodeKinds.length === 0) {
+    throw new UnsupportedPredicateError(
+      "Fulltext predicate must resolve to at least one node kind"
+    );
+  }
+  const tableName = schema.tables.fulltext;
+  const scopedNodes = buildScopedNodeIdsSubquery(fulltextPredicate.field.alias);
+  const fulltextStrategy = dialect.fulltext;
+  if (fulltextStrategy === void 0) {
+    throw new UnsupportedPredicateError(
+      `Fulltext match predicates are not supported for dialect "${dialect.name}"`
+    );
+  }
+  const matchCondition = fulltextStrategy.matchCondition(
+    tableName,
+    query,
+    mode,
+    language
+  );
+  const rankExpression = fulltextStrategy.rankExpression(
+    tableName,
+    query,
+    mode,
+    language
+  );
+  const conditions = [
+    sql`${qualifyColumn(tableName, "graph_id")} = ${graphId}`,
+    compileKindFilter(qualifyColumn(tableName, "node_kind"), nodeKinds),
+    matchCondition
+  ];
+  if (minScore !== void 0) {
+    conditions.push(sql`${rankExpression} >= ${minScore}`);
+  }
+  return sql`
+    ${sql.raw(FULLTEXT_CTE_ALIAS)} AS (
+      SELECT
+        node_id,
+        node_kind,
+        rank,
+        ROW_NUMBER() OVER (ORDER BY rank DESC, node_id ASC) AS ord
+      FROM (
+        SELECT
+          ${qualifyColumn(tableName, "node_id")} AS node_id,
+          ${qualifyColumn(tableName, "node_kind")} AS node_kind,
+          ${rankExpression} AS rank
+        FROM ${schema.fulltextTable}
+        INNER JOIN ${scopedNodes}
+          ON ${sql.raw(`${SCOPED_RELEVANCE_NODES_ALIAS}.node_id`)} =
+             ${qualifyColumn(tableName, "node_id")}
+         AND ${sql.raw(`${SCOPED_RELEVANCE_NODES_ALIAS}.node_kind`)} =
+             ${qualifyColumn(tableName, "node_kind")}
+        WHERE ${sql.join(conditions, sql` AND `)}
+        ORDER BY rank DESC, ${qualifyColumn(tableName, "node_id")} ASC
+        LIMIT ${limit}
+      ) AS fts_inner
+    )
+  `;
+}
+function buildStandardHybridCandidateCte() {
+  return sql`
+    ${sql.raw(HYBRID_CANDIDATES_CTE_ALIAS)} AS (
+      SELECT node_id, node_kind FROM ${sql.raw(EMBEDDINGS_CTE_ALIAS)}
+      UNION
+      SELECT node_id, node_kind FROM ${sql.raw(FULLTEXT_CTE_ALIAS)}
+    )
+  `;
+}
+function compileUserOrderBy(ast, dialect) {
+  if (!ast.orderBy || ast.orderBy.length === 0) return [];
+  const aliasToCte = buildAliasToCteMap(ast);
+  const fragments = [];
+  for (const orderSpec of ast.orderBy) {
+    const valueType = orderSpec.field.valueType;
+    if (valueType === "array" || valueType === "object") {
+      throw new UnsupportedPredicateError(
+        "Ordering by JSON arrays or objects is not supported"
       );
     }
+    const cteAlias = aliasToCte.get(orderSpec.field.alias) ?? `${ALIAS_CTE_PREFIX}${orderSpec.field.alias}`;
+    const field2 = compileFieldValue(
+      orderSpec.field,
+      dialect,
+      valueType,
+      cteAlias
+    );
+    const direction = sql.raw(orderSpec.direction.toUpperCase());
+    const nulls = orderSpec.nulls ?? (orderSpec.direction === "asc" ? "last" : "first");
+    const nullsDirection = sql.raw(nulls === "first" ? "DESC" : "ASC");
+    fragments.push(
+      sql`(${field2} IS NULL) ${nullsDirection}`,
+      sql`${field2} ${direction}`
+    );
   }
-  const allOrders = [distanceOrder, ...additionalOrders];
-  return sql`ORDER BY ${sql.join(allOrders, sql`, `)}`;
+  return fragments;
+}
+function buildStandardFulltextOrderBy(input) {
+  const { ast, dialect } = input;
+  const rankOrder = sql.raw(`${FULLTEXT_CTE_ALIAS}.rank DESC`);
+  const userOrders = compileUserOrderBy(ast, dialect);
+  return sql`ORDER BY ${sql.join([rankOrder, ...userOrders], sql`, `)}`;
+}
+function buildStandardHybridRrfOrderBy(input) {
+  const { ast, dialect, fusion } = input;
+  const k = fusion?.k ?? DEFAULT_RRF_K;
+  const vectorWeight = fusion?.weights?.vector ?? DEFAULT_RRF_WEIGHT;
+  const fulltextWeight = fusion?.weights?.fulltext ?? DEFAULT_RRF_WEIGHT;
+  const rrfOrder = sql.raw(
+    `(COALESCE(${vectorWeight} / (${k} + ${EMBEDDINGS_CTE_ALIAS}.ord), 0) + COALESCE(${fulltextWeight} / (${k} + ${FULLTEXT_CTE_ALIAS}.ord), 0)) DESC`
+  );
+  const idTiebreak = sql.raw(
+    `COALESCE(${FULLTEXT_CTE_ALIAS}.node_id, ${EMBEDDINGS_CTE_ALIAS}.node_id) ASC`
+  );
+  const userOrders = compileUserOrderBy(ast, dialect);
+  return sql`ORDER BY ${sql.join([rrfOrder, ...userOrders, idTiebreak], sql`, `)}`;
+}
+function buildStandardVectorOrderBy(input) {
+  const { ast, dialect } = input;
+  const distanceOrder = sql.raw(`${EMBEDDINGS_CTE_ALIAS}.distance ASC`);
+  const userOrders = compileUserOrderBy(ast, dialect);
+  return sql`ORDER BY ${sql.join([distanceOrder, ...userOrders], sql`, `)}`;
 }
 function buildLimitOffsetClause(input) {
   const { limit, offset } = input;
@@ -2424,6 +2751,74 @@ function buildLimitOffsetClause(input) {
   return parts.length > 0 ? sql.join(parts, sql` `) : void 0;
 }
 
+// src/query/compiler/passes/fulltext.ts
+function runFulltextPredicatePass(ast, dialect) {
+  const fulltextPredicates = extractFulltextMatchPredicates(ast.predicates);
+  if (fulltextPredicates.length > 1) {
+    throw new UnsupportedPredicateError(
+      "Multiple fulltext match predicates in a single query are not supported"
+    );
+  }
+  const fulltextPredicate = fulltextPredicates[0];
+  if (fulltextPredicate === void 0) {
+    return { fulltextPredicate: void 0 };
+  }
+  if (!dialect.capabilities.supportsFulltext) {
+    throw new UnsupportedPredicateError(
+      `Fulltext match predicates are not supported for dialect "${dialect.name}"`
+    );
+  }
+  const strategy = dialect.fulltext;
+  if (strategy === void 0) {
+    throw new UnsupportedPredicateError(
+      `Dialect "${dialect.name}" advertises fulltext support but has no strategy configured`
+    );
+  }
+  if (!strategy.supportedModes.includes(fulltextPredicate.mode)) {
+    throw new UnsupportedPredicateError(
+      `Fulltext query mode "${fulltextPredicate.mode}" is not supported by the "${strategy.name}" strategy. Supported modes: ${strategy.supportedModes.join(", ")}.`
+    );
+  }
+  if (!Number.isFinite(fulltextPredicate.limit) || fulltextPredicate.limit <= 0) {
+    throw new UnsupportedPredicateError(
+      `Fulltext match limit must be a positive finite number, got ${String(fulltextPredicate.limit)}`
+    );
+  }
+  const { minScore } = fulltextPredicate;
+  if (minScore !== void 0 && !Number.isFinite(minScore)) {
+    throw new UnsupportedPredicateError(
+      `Fulltext minScore must be a finite number, got ${String(minScore)}`
+    );
+  }
+  return { fulltextPredicate };
+}
+function resolveFulltextAwareLimit(astLimit, fulltextPredicate) {
+  if (fulltextPredicate === void 0) {
+    return astLimit;
+  }
+  if (astLimit === void 0) {
+    return fulltextPredicate.limit;
+  }
+  return Math.min(astLimit, fulltextPredicate.limit);
+}
+
+// src/query/compiler/passes/fusion.ts
+function runFusionConfigPass(ast, vectorPredicate, fulltextPredicate) {
+  const fusion = ast.fusion;
+  if (fusion === void 0) return { fusion: void 0 };
+  if (vectorPredicate === void 0 || fulltextPredicate === void 0) {
+    throw new UnsupportedPredicateError(
+      `.fuseWith() requires both a .similarTo() and a .$fulltext.matches() predicate in the same query. Remove .fuseWith(), or add the missing predicate.`
+    );
+  }
+  if (vectorPredicate.field.alias !== fulltextPredicate.field.alias) {
+    throw new UnsupportedPredicateError(
+      `.fuseWith() requires .similarTo() and .$fulltext.matches() to target the same node alias. Got vector=${vectorPredicate.field.alias}, fulltext=${fulltextPredicate.field.alias}.`
+    );
+  }
+  return { fusion };
+}
+
 // src/query/compiler/passes/recursive.ts
 function runRecursiveTraversalSelectionPass(ast) {
   const variableLengthTraversal = ast.traversals.find(
@@ -2693,6 +3088,14 @@ function lowerStandardQueryToLogicalPlanNode(input) {
       predicate: input.vectorPredicate
     };
   }
+  if (input.fulltextPredicate !== void 0) {
+    currentNode = {
+      id: nextPlanNodeId(),
+      input: currentNode,
+      op: "fulltext_match",
+      predicate: input.fulltextPredicate
+    };
+  }
   return appendAggregateSortLimitAndProjectNodes(
     currentNode,
     ast,
@@ -2770,17 +3173,30 @@ function lowerComposableQueryToLogicalPlanNode(query, dialect, graphId, nextPlan
       nextPlanNodeId
     });
   }
+  const dialectAdapter = getDialect(dialect);
   const vectorPredicate = runVectorPredicatePass(
     query,
-    getDialect(dialect)
+    dialectAdapter
   ).vectorPredicate;
-  const effectiveLimit = resolveVectorAwareLimit(query.limit, vectorPredicate);
+  const fulltextPredicate = runFulltextPredicatePass(
+    query,
+    dialectAdapter
+  ).fulltextPredicate;
+  const limitAfterVector = resolveVectorAwareLimit(
+    query.limit,
+    vectorPredicate
+  );
+  const effectiveLimit = resolveFulltextAwareLimit(
+    limitAfterVector,
+    fulltextPredicate
+  );
   const loweringInput = {
     ast: query,
     graphId,
     nextPlanNodeId,
     ...effectiveLimit === void 0 ? {} : { effectiveLimit },
-    ...vectorPredicate === void 0 ? {} : { vectorPredicate }
+    ...vectorPredicate === void 0 ? {} : { vectorPredicate },
+    ...fulltextPredicate === void 0 ? {} : { fulltextPredicate }
   };
   return lowerStandardQueryToLogicalPlanNode(loweringInput);
 }
@@ -3287,10 +3703,10 @@ function compileRecursiveProjection(ast, traversal, dialect) {
     sql`${sql.raw(nodeAlias)}_deleted_at`
   ];
   if (vl.depthAlias !== void 0) {
-    fields.push(sql`depth AS ${quoteIdentifier(vl.depthAlias)}`);
+    fields.push(sql`depth AS ${quoteIdentifier2(vl.depthAlias)}`);
   }
   if (vl.pathAlias !== void 0) {
-    fields.push(sql`path AS ${quoteIdentifier(vl.pathAlias)}`);
+    fields.push(sql`path AS ${quoteIdentifier2(vl.pathAlias)}`);
   }
   return sql.join(fields, sql`, `);
 }
@@ -3304,7 +3720,7 @@ function compileRecursiveSelectiveProjection(fields, ast, traversal, dialect) {
     }
     if (field2.isSystemField) {
       const dbColumn = mapSelectiveSystemFieldToColumn(field2.field);
-      return sql`${sql.raw(`${field2.alias}_${dbColumn}`)} AS ${quoteIdentifier(field2.outputName)}`;
+      return sql`${sql.raw(`${field2.alias}_${dbColumn}`)} AS ${quoteIdentifier2(field2.outputName)}`;
     }
     const column = sql.raw(`${field2.alias}_props`);
     const extracted = compileTypedJsonExtract({
@@ -3313,14 +3729,14 @@ function compileRecursiveSelectiveProjection(fields, ast, traversal, dialect) {
       pointer: jsonPointer([field2.field]),
       valueType: field2.valueType
     });
-    return sql`${extracted} AS ${quoteIdentifier(field2.outputName)}`;
+    return sql`${extracted} AS ${quoteIdentifier2(field2.outputName)}`;
   });
   const vl = traversal.variableLength;
   if (vl.depthAlias !== void 0) {
-    columns.push(sql`depth AS ${quoteIdentifier(vl.depthAlias)}`);
+    columns.push(sql`depth AS ${quoteIdentifier2(vl.depthAlias)}`);
   }
   if (vl.pathAlias !== void 0) {
-    columns.push(sql`path AS ${quoteIdentifier(vl.pathAlias)}`);
+    columns.push(sql`path AS ${quoteIdentifier2(vl.pathAlias)}`);
   }
   return sql.join(columns, sql`, `);
 }
@@ -3357,43 +3773,6 @@ function compileLimitOffset(ast) {
   }
   return parts.length > 0 ? sql.join(parts, sql` `) : void 0;
 }
-var DEFAULT_TABLE_NAMES = {
-  nodes: "typegraph_nodes",
-  edges: "typegraph_edges",
-  embeddings: "typegraph_node_embeddings"
-};
-var VALID_IDENTIFIER_PATTERN = /^[a-z_][a-z0-9_$]*$/i;
-function validateTableName(name, label) {
-  if (!name || name.length === 0) {
-    throw new ConfigurationError(`${label} table name cannot be empty`);
-  }
-  if (name.length > MAX_PG_IDENTIFIER_LENGTH) {
-    throw new ConfigurationError(
-      `${label} table name exceeds maximum length of ${MAX_PG_IDENTIFIER_LENGTH} characters`
-    );
-  }
-  if (!VALID_IDENTIFIER_PATTERN.test(name)) {
-    throw new ConfigurationError(
-      `${label} table name "${name}" is not a valid SQL identifier. Table names must start with a letter or underscore and contain only letters, digits, underscores, or dollar signs.`
-    );
-  }
-}
-function quoteIdentifier2(name) {
-  return `"${name.replaceAll('"', '""')}"`;
-}
-function createSqlSchema(names = {}) {
-  const tables = { ...DEFAULT_TABLE_NAMES, ...names };
-  validateTableName(tables.nodes, "nodes");
-  validateTableName(tables.edges, "edges");
-  validateTableName(tables.embeddings, "embeddings");
-  return {
-    tables,
-    nodesTable: sql.raw(quoteIdentifier2(tables.nodes)),
-    edgesTable: sql.raw(quoteIdentifier2(tables.edges)),
-    embeddingsTable: sql.raw(quoteIdentifier2(tables.embeddings))
-  };
-}
-var DEFAULT_SQL_SCHEMA = createSqlSchema();
 
 // src/query/execution/value-decoder.ts
 function nullToUndefined(value) {
@@ -3698,12 +4077,7 @@ async function executeSubgraph(params) {
   for (const row of edgeRows) {
     const edge = mapSubgraphEdgeRow(row, edgeProjectionPlan);
     insertAdjacencyEntry(adjacency, edge.fromId, edge.kind, edge);
-    insertAdjacencyEntry(
-      reverseAdjacency,
-      edge.toId,
-      edge.kind,
-      edge
-    );
+    insertAdjacencyEntry(reverseAdjacency, edge.toId, edge.kind, edge);
   }
   const root = nodesMap.get(ctx.rootId);
   return {
@@ -3877,7 +4251,7 @@ function buildProjectedPropertyColumns(alias, plan, dialect) {
         valueType: fieldPlan.typeInfo?.valueType
       });
       columns.push(
-        sql`CASE WHEN ${sql.raw(alias)}.kind = ${kind} THEN ${extracted} ELSE NULL END AS ${quoteIdentifier(fieldPlan.outputName)}`
+        sql`CASE WHEN ${sql.raw(alias)}.kind = ${kind} THEN ${extracted} ELSE NULL END AS ${quoteIdentifier2(fieldPlan.outputName)}`
       );
     }
   }
@@ -3944,16 +4318,6 @@ function mapSubgraphEdgeRow(row, projectionPlan) {
   applyProjectedFields(projectedEdge, row, kindPlan);
   return projectedEdge;
 }
-
-// src/query/ast.ts
-function mergeEdgeKinds(traversal) {
-  const inverse = traversal.inverseEdgeKinds;
-  if (inverse === void 0 || inverse.length === 0) return traversal.edgeKinds;
-  return [
-    ...traversal.edgeKinds,
-    ...inverse.filter((kind) => !traversal.edgeKinds.includes(kind))
-  ];
-}
 var OPERATOR_MAP = {
   union: "UNION",
   unionAll: "UNION ALL",
@@ -4110,6 +4474,9 @@ function validateSqliteSetOpLeaf(ast) {
   if (hasVectorSimilarityPredicates(ast)) {
     unsupported.push("vector similarity predicates");
   }
+  if (hasFulltextMatchPredicates(ast)) {
+    unsupported.push("fulltext match predicates");
+  }
   if (ast.groupBy !== void 0) {
     unsupported.push("GROUP BY");
   }
@@ -4159,7 +4526,42 @@ function hasVectorSimilarityInExpression(expr) {
       case "between":
       case "array_op":
       case "object_op":
-      case "aggregate_comparison": {
+      case "aggregate_comparison":
+      case "fulltext_match": {
+        return false;
+      }
+    }
+  }
+  return false;
+}
+function hasFulltextMatchPredicates(ast) {
+  return ast.predicates.some(
+    (predicate2) => hasFulltextMatchInExpression(predicate2.expression)
+  );
+}
+function hasFulltextMatchInExpression(expr) {
+  if ("__type" in expr) {
+    switch (expr.__type) {
+      case "and":
+      case "or": {
+        return expr.predicates.some((p) => hasFulltextMatchInExpression(p));
+      }
+      case "not": {
+        return hasFulltextMatchInExpression(expr.predicate);
+      }
+      case "fulltext_match": {
+        return true;
+      }
+      case "exists":
+      case "in_subquery":
+      case "comparison":
+      case "string_op":
+      case "null_check":
+      case "between":
+      case "array_op":
+      case "object_op":
+      case "aggregate_comparison":
+      case "vector_similarity": {
         return false;
       }
     }
@@ -4195,7 +4597,8 @@ function hasSubqueryInExpression(expr) {
       case "array_op":
       case "object_op":
       case "aggregate_comparison":
-      case "vector_similarity": {
+      case "vector_similarity":
+      case "fulltext_match": {
         return false;
       }
     }
@@ -4473,6 +4876,10 @@ function markPredicateFieldsAsRequired(requiredColumnsByAlias, expression) {
       markFieldRefAsRequired(requiredColumnsByAlias, expression.field);
       return;
     }
+    case "fulltext_match": {
+      markFieldRefAsRequired(requiredColumnsByAlias, expression.field);
+      return;
+    }
     case "exists": {
       return;
     }
@@ -4537,7 +4944,8 @@ function hasIdEqualityPredicate(expression, alias) {
     case "aggregate_comparison":
     case "exists":
     case "in_subquery":
-    case "vector_similarity": {
+    case "vector_similarity":
+    case "fulltext_match": {
       return false;
     }
   }
@@ -4578,10 +4986,13 @@ function resolveTraversalCteLimit(ast, predicateIndex) {
   );
   return Math.max(ast.limit, pushdownLimit);
 }
-function canCollapseSelectiveTraversalRowset(ast, vectorPredicate) {
+function canCollapseSelectiveTraversalRowset(ast, vectorPredicate, fulltextPredicate) {
   if (vectorPredicate !== void 0) {
     return false;
   }
+  if (fulltextPredicate !== void 0) {
+    return false;
+  }
   if (ast.traversals.length === 0) {
     return false;
   }
@@ -4621,6 +5032,8 @@ function runStandardQueryPassPipeline(ast, graphId, ctx) {
     collapsedTraversalCteAlias: void 0,
     ctx,
     effectiveLimit: void 0,
+    fulltextPredicate: void 0,
+    fusion: void 0,
     logicalPlan: void 0,
     predicateIndex: buildPredicateIndex(ast),
     requiredColumnsByAlias: void 0,
@@ -4642,6 +5055,39 @@ function runStandardQueryPassPipeline(ast, graphId, ctx) {
     }
   });
   state = vectorPass.state;
+  const fulltextPass = runCompilerPass(state, {
+    name: "fulltext_predicate",
+    execute(currentState) {
+      return runFulltextPredicatePass(
+        currentState.ast,
+        currentState.ctx.dialect
+      ).fulltextPredicate;
+    },
+    update(currentState, fulltextPredicate) {
+      return {
+        ...currentState,
+        fulltextPredicate
+      };
+    }
+  });
+  state = fulltextPass.state;
+  const fusionPass = runCompilerPass(state, {
+    name: "fusion_config",
+    execute(currentState) {
+      return runFusionConfigPass(
+        currentState.ast,
+        currentState.vectorPredicate,
+        currentState.fulltextPredicate
+      ).fusion;
+    },
+    update(currentState, fusion) {
+      return {
+        ...currentState,
+        fusion
+      };
+    }
+  });
+  state = fusionPass.state;
   const temporalPass = runCompilerPass(state, {
     name: "temporal_filters",
     execute(currentState) {
@@ -4676,7 +5122,8 @@ function runStandardQueryPassPipeline(ast, graphId, ctx) {
     execute(currentState) {
       const shouldCollapseSelectiveTraversalRowset = canCollapseSelectiveTraversalRowset(
         currentState.ast,
-        currentState.vectorPredicate
+        currentState.vectorPredicate,
+        currentState.fulltextPredicate
       );
       const lastTraversal = currentState.ast.traversals.at(-1);
       const collapsedTraversalCteAlias = shouldCollapseSelectiveTraversalRowset && lastTraversal !== void 0 ? `cte_${lastTraversal.nodeAlias}` : void 0;
@@ -4712,9 +5159,9 @@ function runStandardQueryPassPipeline(ast, graphId, ctx) {
   state = traversalLimitPass.state;
   state = {
     ...state,
-    effectiveLimit: resolveVectorAwareLimit(
-      state.ast.limit,
-      state.vectorPredicate
+    effectiveLimit: resolveFulltextAwareLimit(
+      resolveVectorAwareLimit(state.ast.limit, state.vectorPredicate),
+      state.fulltextPredicate
     )
   };
   const logicalPlanPass = runCompilerPass(state, {
@@ -4731,7 +5178,8 @@ function runStandardQueryPassPipeline(ast, graphId, ctx) {
           collapsedTraversalCteAlias: currentState.collapsedTraversalCteAlias
         },
         ...currentState.effectiveLimit === void 0 ? {} : { effectiveLimit: currentState.effectiveLimit },
-        ...currentState.vectorPredicate === void 0 ? {} : { vectorPredicate: currentState.vectorPredicate }
+        ...currentState.vectorPredicate === void 0 ? {} : { vectorPredicate: currentState.vectorPredicate },
+        ...currentState.fulltextPredicate === void 0 ? {} : { fulltextPredicate: currentState.fulltextPredicate }
       });
     },
     update(currentState, logicalPlan) {
@@ -4750,11 +5198,11 @@ function compileQuery(ast, graphId, options = "sqlite") {
   const options_ = typeof options === "string" ? { dialect: options } : options;
   const dialect = options_.dialect ?? "sqlite";
   const schema = options_.schema ?? DEFAULT_SQL_SCHEMA;
-  const adapter = getDialect(dialect);
+  const adapter = resolveDialectAdapter(dialect, options_.fulltextStrategy);
   const ctx = {
     dialect: adapter,
     schema,
-    compileQuery: (subAst, subGraphId) => compileQuery(subAst, subGraphId, { dialect, schema })
+    compileQuery: (subAst, subGraphId) => compileQuery(subAst, subGraphId, propagateOptions(options_))
   };
   if (hasVariableLengthTraversal(ast)) {
     const lowered = tryLowerSingleHopRecursiveTraversal(ast);
@@ -4790,15 +5238,29 @@ function compileSetOperation2(op, graphId, options = "sqlite") {
   const options_ = typeof options === "string" ? { dialect: options } : options;
   const dialect = options_.dialect ?? "sqlite";
   const schema = options_.schema ?? DEFAULT_SQL_SCHEMA;
-  const adapter = getDialect(dialect);
+  const adapter = resolveDialectAdapter(dialect, options_.fulltextStrategy);
   return compileSetOperation(
     op,
     graphId,
     adapter,
     schema,
-    (ast, gid) => compileQuery(ast, gid, { dialect, schema })
+    (ast, gid) => compileQuery(ast, gid, propagateOptions(options_))
   );
 }
+function resolveDialectAdapter(dialect, fulltextStrategy) {
+  const baseAdapter = getDialect(dialect);
+  if (fulltextStrategy === void 0 || fulltextStrategy === baseAdapter.fulltext) {
+    return baseAdapter;
+  }
+  return { ...baseAdapter, fulltext: fulltextStrategy };
+}
+function propagateOptions(options_) {
+  return {
+    dialect: options_.dialect ?? "sqlite",
+    ...options_.schema === void 0 ? {} : { schema: options_.schema },
+    ...options_.fulltextStrategy === void 0 ? {} : { fulltextStrategy: options_.fulltextStrategy }
+  };
+}
 function resolveCountAggregateFastPath(ast) {
   if (ast.traversals.length !== 1) {
     return void 0;
@@ -4947,12 +5409,12 @@ function compileCountAggregateFastPath(ast, graphId, ctx, logicalPlan, requiredC
           source.valueType,
           `cte_${source.alias}`
         );
-        return sql`${value} AS ${quoteIdentifier(projectedField.outputName)}`;
+        return sql`${value} AS ${quoteIdentifier2(projectedField.outputName)}`;
       }
       const projectedCountColumn = source.function === "countDistinct" ? countDistinctColumn : countColumn;
       const countValue = sql`${sql.raw(countCteAlias)}.${sql.raw(projectedCountColumn)}`;
       const aggregateValue = traversal.optional ? sql`COALESCE(${countValue}, 0)` : countValue;
-      return sql`${aggregateValue} AS ${quoteIdentifier(projectedField.outputName)}`;
+      return sql`${aggregateValue} AS ${quoteIdentifier2(projectedField.outputName)}`;
     }),
     sql`, `
   );
@@ -4985,11 +5447,37 @@ function compileStandardQuery(ast, graphId, ctx) {
   const handler = STANDARD_QUERY_STRATEGY_HANDLERS[strategy];
   return handler(ast, graphId, ctx);
 }
+function selectStandardOrderBy(input) {
+  const {
+    ast,
+    collapsedTraversalCteAlias,
+    dialect,
+    fulltextPredicate,
+    fusion,
+    vectorPredicate
+  } = input;
+  if (vectorPredicate && fulltextPredicate) {
+    return buildStandardHybridRrfOrderBy({ ast, dialect, fusion });
+  }
+  if (vectorPredicate) {
+    return buildStandardVectorOrderBy({ ast, dialect });
+  }
+  if (fulltextPredicate) {
+    return buildStandardFulltextOrderBy({ ast, dialect });
+  }
+  return buildStandardOrderBy({
+    ast,
+    ...collapsedTraversalCteAlias === void 0 ? {} : { collapsedTraversalCteAlias },
+    dialect
+  });
+}
 function compileStandardQueryWithCteStrategy(ast, graphId, ctx) {
   const { dialect } = ctx;
   const {
     collapsedTraversalCteAlias,
     effectiveLimit,
+    fulltextPredicate,
+    fusion,
     logicalPlan,
     predicateIndex,
     requiredColumnsByAlias,
@@ -5010,7 +5498,7 @@ function compileStandardQueryWithCteStrategy(ast, graphId, ctx) {
       { phase: "standard-pass-pipeline" }
     );
   }
-  if (!vectorPredicate) {
+  if (!vectorPredicate && !fulltextPredicate) {
     const fastPathSql = compileCountAggregateFastPath(
       ast,
       graphId,
@@ -5056,7 +5544,29 @@ function compileStandardQueryWithCteStrategy(ast, graphId, ctx) {
     );
   }
   if (vectorPredicate) {
-    ctes.push(buildStandardEmbeddingsCte({ ctx, graphId, vectorPredicate }));
+    const nodeKinds = getNodeKindsForAlias(ast, vectorPredicate.field.alias);
+    ctes.push(
+      buildStandardEmbeddingsCte({
+        ctx,
+        graphId,
+        nodeKinds,
+        vectorPredicate
+      })
+    );
+  }
+  if (fulltextPredicate) {
+    const nodeKinds = getNodeKindsForAlias(ast, fulltextPredicate.field.alias);
+    ctes.push(
+      buildStandardFulltextCte({
+        ctx,
+        fulltextPredicate,
+        graphId,
+        nodeKinds
+      })
+    );
+  }
+  if (getHybridTargetAlias(vectorPredicate, fulltextPredicate) !== void 0) {
+    ctes.push(buildStandardHybridCandidateCte());
   }
   const projection = buildStandardProjection({
     ast,
@@ -5066,14 +5576,18 @@ function compileStandardQueryWithCteStrategy(ast, graphId, ctx) {
   const fromClause = buildStandardFromClause({
     ast,
     ...collapsedTraversalCteAlias === void 0 ? {} : { collapsedTraversalCteAlias },
-    ...vectorPredicate === void 0 ? {} : { vectorPredicate }
+    ...vectorPredicate === void 0 ? {} : { vectorPredicate },
+    ...fulltextPredicate === void 0 ? {} : { fulltextPredicate }
   });
   const groupBy = buildStandardGroupBy({ ast, dialect });
   const having2 = buildStandardHaving({ ast, ctx });
-  const orderBy = vectorPredicate ? buildStandardVectorOrderBy({ ast, dialect }) : buildStandardOrderBy({
+  const orderBy = selectStandardOrderBy({
     ast,
-    ...collapsedTraversalCteAlias === void 0 ? {} : { collapsedTraversalCteAlias },
-    dialect
+    collapsedTraversalCteAlias,
+    dialect,
+    fulltextPredicate,
+    fusion,
+    vectorPredicate
   });
   const limitOffset = buildLimitOffsetClause({
     limit: effectiveLimit,
@@ -5494,11 +6008,7 @@ function buildComparisonPredicate(field2, op, value) {
   };
 }
 function buildCursorFromContext(context, orderBy, direction) {
-  return buildCursorFromRow(
-    context,
-    orderBy,
-    direction
-  );
+  return buildCursorFromRow(context, orderBy, direction);
 }
 function buildPaginatedResult(data, orderedRows, orderBy, limit, hasMore, isBackward, cursor, buildContext) {
   let nextCursor;
@@ -6091,59 +6601,41 @@ function validateSqlIdentifier(alias) {
     );
   }
 }
-function throwInvalidVectorPredicatePlacement(path) {
-  throw new ValidationError(
-    "Vector similarity predicates cannot be nested under OR or NOT. Use top-level AND combinations instead.",
-    {
-      issues: [
-        {
-          path,
-          message: "Vector similarity predicates are only supported at top-level or inside AND groups."
-        }
-      ]
-    },
-    {
-      suggestion: "Rewrite the predicate to keep vector similarity at top-level or combine with additional filters using AND."
-    }
-  );
-}
-function validateVectorPredicateExpression(expression, inDisallowedBranch, path) {
+function validateStructuralPredicatePlacement(expression, matchType, buildError, inDisallowedBranch, path) {
+  if (expression.__type === matchType) {
+    if (inDisallowedBranch) buildError(path);
+    return;
+  }
   switch (expression.__type) {
-    case "vector_similarity": {
-      if (inDisallowedBranch) {
-        throwInvalidVectorPredicatePlacement(path);
-      }
-      return;
-    }
     case "and": {
-      for (const [
-        predicateIndex,
-        predicate2
-      ] of expression.predicates.entries()) {
-        validateVectorPredicateExpression(
-          predicate2,
+      for (const [index, child] of expression.predicates.entries()) {
+        validateStructuralPredicatePlacement(
+          child,
+          matchType,
+          buildError,
           inDisallowedBranch,
-          `${path}.predicates[${predicateIndex}]`
+          `${path}.predicates[${index}]`
         );
       }
       return;
     }
     case "or": {
-      for (const [
-        predicateIndex,
-        predicate2
-      ] of expression.predicates.entries()) {
-        validateVectorPredicateExpression(
-          predicate2,
+      for (const [index, child] of expression.predicates.entries()) {
+        validateStructuralPredicatePlacement(
+          child,
+          matchType,
+          buildError,
           true,
-          `${path}.predicates[${predicateIndex}]`
+          `${path}.predicates[${index}]`
         );
       }
       return;
     }
     case "not": {
-      validateVectorPredicateExpression(
+      validateStructuralPredicatePlacement(
         expression.predicate,
+        matchType,
+        buildError,
         true,
         `${path}.predicate`
       );
@@ -6157,24 +6649,108 @@ function validateVectorPredicateExpression(expression, inDisallowedBranch, path)
     case "object_op":
     case "aggregate_comparison":
     case "exists":
-    case "in_subquery": {
+    case "in_subquery":
+    case "vector_similarity":
+    case "fulltext_match": {
       return;
     }
   }
 }
+function throwInvalidVectorPredicatePlacement(path) {
+  throw new ValidationError(
+    "Vector similarity predicates cannot be nested under OR or NOT. Use top-level AND combinations instead.",
+    {
+      issues: [
+        {
+          path,
+          message: "Vector similarity predicates are only supported at top-level or inside AND groups."
+        }
+      ]
+    },
+    {
+      suggestion: "Rewrite the predicate to keep vector similarity at top-level or combine with additional filters using AND."
+    }
+  );
+}
+function throwInvalidFulltextPredicatePlacement(path) {
+  throw new ValidationError(
+    "Fulltext match predicates (.matches()) cannot be nested under OR or NOT. Use top-level AND combinations instead.",
+    {
+      issues: [
+        {
+          path,
+          message: "Fulltext match predicates are only supported at top-level or inside AND groups."
+        }
+      ]
+    },
+    {
+      suggestion: "Restructure your query so the fulltext match appears at the top level of a whereNode() or inside an .and() combination."
+    }
+  );
+}
 function validateVectorPredicatePlacement(predicates) {
-  for (const [predicateIndex, predicate2] of predicates.entries()) {
-    validateVectorPredicateExpression(
+  for (const [index, predicate2] of predicates.entries()) {
+    validateStructuralPredicatePlacement(
+      predicate2.expression,
+      "vector_similarity",
+      throwInvalidVectorPredicatePlacement,
+      false,
+      `predicates[${index}].expression`
+    );
+  }
+}
+function validateFulltextPredicatePlacement(predicates) {
+  for (const [index, predicate2] of predicates.entries()) {
+    validateStructuralPredicatePlacement(
       predicate2.expression,
+      "fulltext_match",
+      throwInvalidFulltextPredicatePlacement,
       false,
-      `predicates[${predicateIndex}].expression`
+      `predicates[${index}].expression`
+    );
+  }
+}
+function validateHybridFusionOptions(options) {
+  const method = options.method;
+  if (method !== void 0 && method !== "rrf") {
+    throw new ValidationError(`Unsupported fusion method: ${method}`, {
+      issues: [{ path: "fusion.method", message: `Only "rrf" is supported.` }]
+    });
+  }
+  const { k } = options;
+  if (k !== void 0 && (!Number.isFinite(k) || k <= 0)) {
+    throw new ValidationError(
+      `Fusion k must be a positive finite number, got: ${String(k)}`,
+      {
+        issues: [{ path: "fusion.k", message: "Must be a positive number." }]
+      }
     );
   }
+  const weights = options.weights;
+  if (weights !== void 0) {
+    for (const key of ["vector", "fulltext"]) {
+      const weight = weights[key];
+      if (weight !== void 0 && (!Number.isFinite(weight) || weight < 0)) {
+        throw new ValidationError(
+          `Fusion weight for "${key}" must be a non-negative finite number, got: ${String(weight)}`,
+          {
+            issues: [
+              {
+                path: `fusion.weights.${key}`,
+                message: "Must be a non-negative number."
+              }
+            ]
+          }
+        );
+      }
+    }
+  }
 }
 
 // src/query/builder/ast-builder.ts
 function buildQueryAst(config, state) {
   validateVectorPredicatePlacement(state.predicates);
+  validateFulltextPredicatePlacement(state.predicates);
   const temporalMode = {
     mode: state.temporalMode
   };
@@ -6198,7 +6774,18 @@ function buildQueryAst(config, state) {
     ...state.limit !== void 0 && { limit: state.limit },
     ...state.offset !== void 0 && { offset: state.offset },
     ...state.groupBy !== void 0 && { groupBy: state.groupBy },
-    ...state.having !== void 0 && { having: state.having }
+    ...state.having !== void 0 && { having: state.having },
+    ...state.fusion !== void 0 && { fusion: state.fusion }
+  };
+}
+
+// src/query/builder/compile-options.ts
+function buildCompileOptions(config) {
+  const fulltextStrategy = config.backend?.fulltextStrategy;
+  return {
+    dialect: config.dialect ?? "sqlite",
+    schema: config.schema,
+    ...fulltextStrategy === void 0 ? {} : { fulltextStrategy }
   };
 }
 function toLiteral(value) {
@@ -6300,7 +6887,8 @@ function substitutePredicateExpression(expr, bindings) {
     case "array_op":
     case "object_op":
     case "aggregate_comparison":
-    case "vector_similarity": {
+    case "vector_similarity":
+    case "fulltext_match": {
       return expr;
     }
     case "exists": {
@@ -6552,7 +7140,8 @@ function collectParameterMetadataFromExpression(expression, names, stringOpParam
     case "array_op":
     case "object_op":
     case "aggregate_comparison":
-    case "vector_similarity": {
+    case "vector_similarity":
+    case "fulltext_match": {
       return;
     }
     case "exists": {
@@ -6907,10 +7496,7 @@ var ExecutableQuery = class _ExecutableQuery {
    * Builds compile options from the config.
    */
   #compileOptions() {
-    return {
-      dialect: this.#config.dialect ?? "sqlite",
-      schema: this.#config.schema
-    };
+    return buildCompileOptions(this.#config);
   }
   #requireBackend() {
     const { backend } = this.#config;
@@ -7625,14 +8211,8 @@ var ExecutableAggregateQuery = class _ExecutableAggregateQuery {
     this.#cachedCompiled = compiled;
     return compiled;
   }
-  /**
-   * Builds compile options from the config.
-   */
   #compileOptions() {
-    return {
-      dialect: this.#config.dialect ?? "sqlite",
-      schema: this.#config.schema
-    };
+    return buildCompileOptions(this.#config);
   }
   /**
    * Executes the query and returns typed results.
@@ -8359,6 +8939,36 @@ var QueryBuilder = class _QueryBuilder {
       having: predicate2
     });
   }
+  /**
+   * 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) {
+    validateHybridFusionOptions(options);
+    return new _QueryBuilder(this.#config, {
+      ...this.#state,
+      fusion: options
+    });
+  }
   /**
    * Applies a query fragment to transform this builder.
    *
@@ -8417,35 +9027,7 @@ var QueryBuilder = class _QueryBuilder {
     return this.#buildFieldBuilderForTypeInfo(ref, typeInfo);
   }
   #buildFieldBuilderForTypeInfo(ref, typeInfo) {
-    if (!typeInfo) {
-      return baseField(ref);
-    }
-    switch (typeInfo.valueType) {
-      case "string": {
-        return stringField(ref);
-      }
-      case "number": {
-        return numberField(ref);
-      }
-      case "boolean": {
-        return baseField(ref);
-      }
-      case "date": {
-        return dateField(ref);
-      }
-      case "array": {
-        return arrayField(ref);
-      }
-      case "object": {
-        return objectField(ref, { typeInfo });
-      }
-      case "embedding": {
-        return embeddingField(ref);
-      }
-      case "unknown": {
-        return baseField(ref);
-      }
-    }
+    return buildFieldBuilderForTypeInfo(ref, typeInfo);
   }
   #createNodeAccessor(alias) {
     const kindNames = this.#getKindNamesForAlias(alias);
@@ -8455,6 +9037,10 @@ var QueryBuilder = class _QueryBuilder {
     const kindAccessor = stringField(
       fieldRef(alias, ["kind"], { valueType: "string" })
     );
+    const fulltextAccessor = createFulltextAccessor(
+      alias,
+      () => this.#hasSearchableField(kindNames)
+    );
     return new Proxy({}, {
       get: (_, property) => {
         if (typeof property === "symbol") return;
@@ -8462,10 +9048,15 @@ var QueryBuilder = class _QueryBuilder {
         if (property === "toJSON") return;
         if (property === "id") return idAccessor;
         if (property === "kind") return kindAccessor;
+        if (property === "$fulltext") return fulltextAccessor;
         return this.#getFieldBuilderForProperty(kindNames, property, alias);
       }
     });
   }
+  #hasSearchableField(kindNames) {
+    if (!kindNames) return false;
+    return this.#config.schemaIntrospector.hasSearchableField(kindNames);
+  }
   #expandTraversalEdgeKinds(edgeKind, includeImplyingEdges) {
     return includeImplyingEdges ? this.#config.registry.expandImplyingEdges(edgeKind) : [edgeKind];
   }
@@ -8691,14 +9282,8 @@ var UnionableQuery = class _UnionableQuery {
     this.#cachedCompiled = compiled;
     return compiled;
   }
-  /**
-   * Builds compile options from the config.
-   */
   #compileOptions() {
-    return {
-      dialect: this.#config.dialect ?? "sqlite",
-      schema: this.#config.schema
-    };
+    return buildCompileOptions(this.#config);
   }
   /**
    * Executes the combined query.
@@ -8914,12 +9499,8 @@ function offsetFragment(n) {
 }
 
 // src/query/builder/index.ts
-setQueryBuilderClass(
-  QueryBuilder
-);
-setUnionableQueryClass(
-  UnionableQuery
-);
+setQueryBuilderClass(QueryBuilder);
+setUnionableQueryClass(UnionableQuery);
 
 // src/query/builder.ts
 function createQueryBuilder(graphId, registry, options) {
@@ -8950,7 +9531,8 @@ function createQueryBuilder(graphId, registry, options) {
     temporalMode: "current",
     asOf: void 0,
     groupBy: void 0,
-    having: void 0
+    having: void 0,
+    fusion: void 0
   };
   return new QueryBuilder(config, initialState);
 }
@@ -9291,20 +9873,13 @@ function createEdgeCollection(config) {
     const result = {};
     if (options?.matchOn !== void 0)
       result.matchOn = options.matchOn;
-    if (options?.props !== void 0)
-      result.props = options.props;
+    if (options?.props !== void 0) result.props = options.props;
     return result;
   }
   return {
     async create(from, to, props, options) {
       const result = await executeEdgeCreate2(
-        buildCreateEdgeInput(
-          kind,
-          from,
-          to,
-          props ?? {},
-          options
-        ),
+        buildCreateEdgeInput(kind, from, to, props ?? {}, options),
         backend
       );
       return narrowEdge(result);
@@ -9430,10 +10005,7 @@ function createEdgeCollection(config) {
       return backend.countEdgesByKind(params);
     },
     async bulkCreate(items) {
-      const batchInputs = mapBulkEdgeInputs(
-        kind,
-        items
-      );
+      const batchInputs = mapBulkEdgeInputs(kind, items);
       if (backend.capabilities.transactions && "transaction" in backend) {
         const results2 = await backend.transaction(
           async (txBackend) => executeEdgeCreateBatch2(batchInputs, txBackend)
@@ -9469,11 +10041,7 @@ function createEdgeCollection(config) {
           if (existing) {
             toUpdate.push({
               index: itemIndex,
-              input: buildUpdateEdgeInput(
-                item.id,
-                item.props ?? {},
-                item
-              ),
+              input: buildUpdateEdgeInput(item.id, item.props ?? {}, item),
               clearDeleted: existing.deleted_at !== void 0
             });
           } else {
@@ -9512,10 +10080,7 @@ function createEdgeCollection(config) {
       return upsertAll(backend);
     },
     async bulkInsert(items) {
-      const batchInputs = mapBulkEdgeInputs(
-        kind,
-        items
-      );
+      const batchInputs = mapBulkEdgeInputs(kind, items);
       if (backend.capabilities.transactions && "transaction" in backend) {
         await backend.transaction(async (txBackend) => {
           await executeEdgeCreateNoReturnBatch2(batchInputs, txBackend);
@@ -9666,11 +10231,7 @@ function createNodeCollection(config) {
     async getByIds(ids, options) {
       if (ids.length === 0) return [];
       if (backend.getNodes !== void 0) {
-        const rows = await backend.getNodes(
-          graphId,
-          kind,
-          ids
-        );
+        const rows = await backend.getNodes(graphId, kind, ids);
         const rowMap = /* @__PURE__ */ new Map();
         for (const row of rows) {
           rowMap.set(row.id, row);
@@ -9751,11 +10312,7 @@ function createNodeCollection(config) {
       return backend.countNodesByKind(params);
     },
     async upsertById(id, props, options) {
-      return this.upsertByIdFromRecord(
-        id,
-        props,
-        options
-      );
+      return this.upsertByIdFromRecord(id, props, options);
     },
     async upsertByIdFromRecord(id, data, options) {
       const existing = await backend.getNode(graphId, kind, id);
@@ -9775,10 +10332,7 @@ function createNodeCollection(config) {
       return narrowNode(result);
     },
     async bulkCreate(items) {
-      const batchInputs = mapBulkNodeInputs(
-        kind,
-        items
-      );
+      const batchInputs = mapBulkNodeInputs(kind, items);
       if (backend.capabilities.transactions && "transaction" in backend) {
         const results2 = await backend.transaction(
           async (txBackend) => executeNodeCreateBatch2(batchInputs, txBackend)
@@ -9801,11 +10355,7 @@ function createNodeCollection(config) {
             if (row !== void 0) existingMap.set(row.id, row);
           }
         } else {
-          const rows = await target.getNodes(
-            graphId,
-            kind,
-            ids
-          );
+          const rows = await target.getNodes(graphId, kind, ids);
           for (const row of rows) {
             existingMap.set(row.id, row);
           }
@@ -9818,22 +10368,13 @@ function createNodeCollection(config) {
           if (existing) {
             toUpdate.push({
               index: itemIndex,
-              input: buildUpdateInput(
-                kind,
-                item.id,
-                item.props,
-                item
-              ),
+              input: buildUpdateInput(kind, item.id, item.props, item),
               clearDeleted: existing.deleted_at !== void 0
             });
           } else {
             toCreate.push({
               index: itemIndex,
-              input: buildCreateInput(
-                kind,
-                item.props,
-                item
-              )
+              input: buildCreateInput(kind, item.props, item)
             });
           }
           itemIndex++;
@@ -9860,10 +10401,7 @@ function createNodeCollection(config) {
       return upsertAll(backend);
     },
     async bulkInsert(items) {
-      const batchInputs = mapBulkNodeInputs(
-        kind,
-        items
-      );
+      const batchInputs = mapBulkNodeInputs(kind, items);
       if (backend.capabilities.transactions && "transaction" in backend) {
         await backend.transaction(async (txBackend) => {
           await executeNodeCreateNoReturnBatch2(batchInputs, txBackend);
@@ -10969,15 +11507,19 @@ async function executeEdgeBulkGetOrCreateByEndpoints(ctx, kind, items, backend,
 }
 
 // src/store/embedding-sync.ts
+var embeddingFieldsCache = /* @__PURE__ */ new WeakMap();
 function getEmbeddingFields(schema) {
-  if (schema.type !== "object") {
-    return [];
-  }
+  const cached = embeddingFieldsCache.get(schema);
+  if (cached) return cached;
+  const fields = computeEmbeddingFields(schema);
+  embeddingFieldsCache.set(schema, fields);
+  return fields;
+}
+function computeEmbeddingFields(schema) {
+  if (schema.type !== "object") return [];
   const def = schema.def;
   const shape = def.shape;
-  if (!shape) {
-    return [];
-  }
+  if (!shape) return [];
   const fields = [];
   for (const [fieldPath, fieldSchema] of Object.entries(shape)) {
     const dimensions = getEmbeddingDimensionsFromField(fieldSchema);
@@ -11064,6 +11606,101 @@ function isValidEmbeddingValue(value) {
   return value.every((n) => typeof n === "number" && Number.isFinite(n));
 }
 
+// src/store/fulltext-sync.ts
+var searchableFieldsCache = /* @__PURE__ */ new WeakMap();
+function getSearchableFields(schema) {
+  const cached = searchableFieldsCache.get(schema);
+  if (cached) return cached;
+  const fields = computeSearchableFields(schema);
+  searchableFieldsCache.set(schema, fields);
+  return fields;
+}
+function computeSearchableFields(schema) {
+  if (schema.type !== "object") return [];
+  const def = schema.def;
+  const shape = def.shape;
+  if (!shape) return [];
+  const fields = [];
+  for (const [fieldPath, fieldSchema] of Object.entries(shape)) {
+    const metadata = getSearchableMetadata(fieldSchema);
+    if (metadata !== void 0) {
+      fields.push({ fieldPath, metadata });
+    }
+  }
+  warnIfConflictingLanguages(fields);
+  return fields;
+}
+function warnIfConflictingLanguages(fields) {
+  if (fields.length < 2) return;
+  const languages = new Set(fields.map((field2) => field2.metadata.language));
+  if (languages.size < 2) return;
+  if (typeof console === "undefined" || typeof console.warn !== "function") {
+    return;
+  }
+  const fieldSummary = fields.map((field2) => `${field2.fieldPath}=${field2.metadata.language}`).join(", ");
+  const winning = fields[0]?.metadata.language ?? DEFAULT_SEARCHABLE_LANGUAGE;
+  console.warn(
+    `[typegraph] searchable() fields declare conflicting languages (${fieldSummary}). The first field's language ("${winning}") is recorded on the fulltext row; true multilingual indexing requires a dedicated node kind per language.`
+  );
+}
+var FIELD_SEPARATOR = "\n";
+function resolveCombinedLanguage(fields) {
+  return fields[0]?.metadata.language ?? DEFAULT_SEARCHABLE_LANGUAGE;
+}
+function computeFulltextContent(schema, props) {
+  const searchableFields = getSearchableFields(schema);
+  if (searchableFields.length === 0) return void 0;
+  const parts = [];
+  for (const field2 of searchableFields) {
+    const value = props[field2.fieldPath];
+    if (typeof value === "string" && value.length > 0) {
+      parts.push(value);
+    }
+  }
+  if (parts.length === 0) return void 0;
+  return {
+    content: parts.join(FIELD_SEPARATOR),
+    language: resolveCombinedLanguage(searchableFields)
+  };
+}
+async function syncFulltext(ctx, schema, props) {
+  const { backend } = ctx;
+  if (!backend.upsertFulltext || !backend.deleteFulltext) {
+    return;
+  }
+  const computed = computeFulltextContent(schema, props);
+  if (computed !== void 0) {
+    await backend.upsertFulltext({
+      graphId: ctx.graphId,
+      nodeKind: ctx.nodeKind,
+      nodeId: ctx.nodeId,
+      content: computed.content,
+      language: computed.language
+    });
+    return;
+  }
+  if (getSearchableFields(schema).length === 0) return;
+  await backend.deleteFulltext({
+    graphId: ctx.graphId,
+    nodeKind: ctx.nodeKind,
+    nodeId: ctx.nodeId
+  });
+}
+async function deleteNodeFulltext(ctx, schema) {
+  const { backend } = ctx;
+  if (!backend.deleteFulltext) {
+    return;
+  }
+  if (getSearchableFields(schema).length === 0) {
+    return;
+  }
+  await backend.deleteFulltext({
+    graphId: ctx.graphId,
+    nodeKind: ctx.nodeKind,
+    nodeId: ctx.nodeId
+  });
+}
+
 // src/store/uniqueness.ts
 async function checkUniquenessConstraints(ctx, kind, id, props, constraints) {
   for (const constraint of constraints) {
@@ -11257,6 +11894,9 @@ function createUniquenessContext(graphId, registry, backend) {
 function createEmbeddingSyncContext(graphId, nodeKind, nodeId, backend) {
   return { graphId, nodeKind, nodeId, backend };
 }
+function createFulltextSyncContext(graphId, nodeKind, nodeId, backend) {
+  return { graphId, nodeKind, nodeId, backend };
+}
 function createNodeBatchValidationBackend(graphId, registry, backend) {
   const nodeCache = /* @__PURE__ */ new Map();
   const pendingNodes = /* @__PURE__ */ new Map();
@@ -11414,6 +12054,11 @@ async function finalizeNodeCreate(ctx, prepared, backend) {
     prepared.nodeKind.schema,
     prepared.validatedProps
   );
+  await syncFulltext(
+    createFulltextSyncContext(ctx.graphId, prepared.kind, prepared.id, backend),
+    prepared.nodeKind.schema,
+    prepared.validatedProps
+  );
 }
 async function performNodeUpdate(ctx, input, backend, options) {
   const { kind, id } = input;
@@ -11454,6 +12099,11 @@ async function performNodeUpdate(ctx, input, backend, options) {
     nodeKind.schema,
     validatedProps
   );
+  await syncFulltext(
+    createFulltextSyncContext(ctx.graphId, kind, id, backend),
+    nodeKind.schema,
+    validatedProps
+  );
   return rowToNode(row);
 }
 async function enforceDeleteBehavior(ctx, kind, id, mode, backend, registration) {
@@ -11670,6 +12320,10 @@ async function executeNodeDelete(ctx, kind, id, backend) {
       createEmbeddingSyncContext(ctx.graphId, kind, id, backend),
       nodeKind.schema
     );
+    await deleteNodeFulltext(
+      createFulltextSyncContext(ctx.graphId, kind, id, backend),
+      nodeKind.schema
+    );
   });
 }
 async function executeNodeHardDelete(ctx, kind, id, backend) {
@@ -11976,6 +12630,503 @@ async function executeNodeBulkGetOrCreateByConstraint(ctx, kind, constraintName,
   return results;
 }
 
+// src/store/fulltext-rebuild.ts
+var DEFAULT_PAGE_SIZE = 500;
+var DEFAULT_MAX_SKIPPED_IDS = 1e4;
+function validatePageSize(value) {
+  if (value === void 0) return DEFAULT_PAGE_SIZE;
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new ValidationError(
+      `pageSize must be a positive integer, got: ${String(value)}`,
+      {
+        issues: [{ path: "pageSize", message: "Must be a positive integer." }]
+      }
+    );
+  }
+  return value;
+}
+function validateMaxSkippedIds(value) {
+  if (value === void 0) return DEFAULT_MAX_SKIPPED_IDS;
+  if (!Number.isInteger(value) || value < 0) {
+    throw new ValidationError(
+      `maxSkippedIds must be a non-negative integer, got: ${String(value)}`,
+      {
+        issues: [
+          {
+            path: "maxSkippedIds",
+            message: "Must be a non-negative integer."
+          }
+        ]
+      }
+    );
+  }
+  return value;
+}
+function isPropsObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function rebuildFulltextIndex(ctx, nodeKind, options) {
+  const { backend, registry } = ctx;
+  if (!backend.upsertFulltext || !backend.deleteFulltext) {
+    throw new ConfigurationError(
+      "Backend does not support fulltext; cannot rebuild index",
+      { backend: backend.dialect, capability: "fulltext" }
+    );
+  }
+  const pageSize = validatePageSize(options.pageSize);
+  const maxSkippedIds = validateMaxSkippedIds(options.maxSkippedIds);
+  const targetKinds = nodeKind === void 0 ? [...registry.nodeKinds.keys()] : [nodeKind];
+  const rebuiltKinds = [];
+  let processed = 0;
+  let upserted = 0;
+  let cleared = 0;
+  let skipped = 0;
+  const skippedIds = [];
+  for (const kind of targetKinds) {
+    const nodeType = registry.getNodeType(kind);
+    if (!nodeType) {
+      throw new ConfigurationError(`Unknown node kind: ${kind}`, { kind });
+    }
+    if (getSearchableFields(nodeType.schema).length === 0) {
+      continue;
+    }
+    rebuiltKinds.push(kind);
+    let cursor;
+    for (; ; ) {
+      const rows = await backend.findNodesByKind({
+        graphId: ctx.graphId,
+        kind,
+        limit: pageSize,
+        excludeDeleted: false,
+        orderBy: "id",
+        ...cursor === void 0 ? {} : { after: cursor }
+      });
+      if (rows.length === 0) break;
+      const pageResult = processPage(nodeType.schema, rows);
+      skipped += pageResult.skipped;
+      const remaining = maxSkippedIds - skippedIds.length;
+      if (remaining > 0 && pageResult.skippedIds.length > 0) {
+        skippedIds.push(...pageResult.skippedIds.slice(0, remaining));
+      }
+      await backend.transaction(async (tx) => {
+        if (pageResult.toUpsert.length > 0) {
+          if (tx.upsertFulltextBatch) {
+            await tx.upsertFulltextBatch({
+              graphId: ctx.graphId,
+              nodeKind: kind,
+              rows: pageResult.toUpsert
+            });
+          } else if (tx.upsertFulltext) {
+            for (const item of pageResult.toUpsert) {
+              await tx.upsertFulltext({
+                graphId: ctx.graphId,
+                nodeKind: kind,
+                nodeId: item.nodeId,
+                content: item.content,
+                language: item.language
+              });
+            }
+          }
+        }
+        if (pageResult.toDelete.length > 0) {
+          if (tx.deleteFulltextBatch) {
+            await tx.deleteFulltextBatch({
+              graphId: ctx.graphId,
+              nodeKind: kind,
+              nodeIds: pageResult.toDelete
+            });
+          } else if (tx.deleteFulltext) {
+            for (const nodeId of pageResult.toDelete) {
+              await tx.deleteFulltext({
+                graphId: ctx.graphId,
+                nodeKind: kind,
+                nodeId
+              });
+            }
+          }
+        }
+      });
+      processed += rows.length;
+      upserted += pageResult.toUpsert.length;
+      cleared += pageResult.toDelete.length;
+      const lastRow = rows.at(-1);
+      if (!lastRow) break;
+      cursor = lastRow.id;
+      if (rows.length < pageSize) break;
+    }
+  }
+  return {
+    kinds: rebuiltKinds,
+    processed,
+    upserted,
+    cleared,
+    skipped,
+    skippedIds,
+    skippedTruncated: skipped > skippedIds.length
+  };
+}
+function processPage(schema, rows) {
+  const toUpsert = [];
+  const toDelete = [];
+  const skippedIds = [];
+  let skipped = 0;
+  for (const row of rows) {
+    if (row.deleted_at !== void 0) {
+      toDelete.push(row.id);
+      continue;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(row.props);
+    } catch {
+      skipped += 1;
+      skippedIds.push(row.id);
+      continue;
+    }
+    if (!isPropsObject(parsed)) {
+      skipped += 1;
+      skippedIds.push(row.id);
+      continue;
+    }
+    const computed = computeFulltextContent(schema, parsed);
+    if (computed === void 0) {
+      toDelete.push(row.id);
+    } else {
+      toUpsert.push({
+        nodeId: row.id,
+        content: computed.content,
+        language: computed.language
+      });
+    }
+  }
+  return { toUpsert, toDelete, skipped, skippedIds };
+}
+
+// src/store/search.ts
+async function executeFulltextSearch(ctx, nodeKind, options) {
+  const { backend, graphId } = ctx;
+  if (!backend.fulltextSearch) {
+    throw new ConfigurationError("Backend does not support fulltext search", {
+      backend: backend.dialect,
+      capability: "fulltext"
+    });
+  }
+  if (!Number.isInteger(options.limit) || options.limit <= 0) {
+    throw new RangeError(
+      `fulltextSearch.limit must be a positive integer, got: ${options.limit}`
+    );
+  }
+  validateFulltextCallOptions(backend, {
+    mode: options.mode,
+    includeSnippets: options.includeSnippets,
+    language: options.language
+  });
+  const params = {
+    graphId,
+    nodeKind,
+    query: options.query,
+    limit: options.limit,
+    ...options.mode ? { mode: options.mode } : {},
+    ...options.language ? { language: options.language } : {},
+    ...options.minScore === void 0 ? {} : { minScore: options.minScore },
+    ...options.includeSnippets === void 0 ? {} : { includeSnippets: options.includeSnippets }
+  };
+  const rows = await backend.fulltextSearch(params);
+  if (rows.length === 0) return [];
+  const ids = rows.map((r) => r.nodeId);
+  const nodeMap = await fetchNodesByIds(backend, graphId, nodeKind, ids);
+  const hits = [];
+  let rank = 1;
+  for (const row of rows) {
+    const node = nodeMap.get(row.nodeId);
+    if (!node) continue;
+    hits.push({
+      node,
+      score: row.score,
+      rank,
+      ...row.snippet === void 0 ? {} : { snippet: row.snippet }
+    });
+    rank += 1;
+  }
+  return hits;
+}
+async function executeHybridSearch(ctx, nodeKind, options) {
+  const { backend, graphId } = ctx;
+  if (!backend.vectorSearch) {
+    throw new ConfigurationError("Backend does not support vector search", {
+      backend: backend.dialect,
+      capability: "vector"
+    });
+  }
+  if (!backend.fulltextSearch) {
+    throw new ConfigurationError("Backend does not support fulltext search", {
+      backend: backend.dialect,
+      capability: "fulltext"
+    });
+  }
+  if (!Number.isInteger(options.limit) || options.limit <= 0) {
+    throw new RangeError(
+      `hybridSearch.limit must be a positive integer, got: ${options.limit}`
+    );
+  }
+  if (options.fusion !== void 0) {
+    validateHybridFusionOptions(options.fusion);
+  }
+  validateFulltextCallOptions(backend, {
+    mode: options.fulltext.mode,
+    includeSnippets: options.fulltext.includeSnippets,
+    language: options.fulltext.language
+  });
+  const fusionK = options.fusion?.k ?? DEFAULT_RRF_K;
+  const vectorWeight = options.fusion?.weights?.vector ?? DEFAULT_RRF_WEIGHT;
+  const fulltextWeight = options.fusion?.weights?.fulltext ?? DEFAULT_RRF_WEIGHT;
+  const overFetchMultiplier = 4;
+  const vectorK = options.vector.k ?? options.limit * overFetchMultiplier;
+  const fulltextK = options.fulltext.k ?? options.limit * overFetchMultiplier;
+  const vectorPromise = backend.vectorSearch({
+    graphId,
+    nodeKind,
+    fieldPath: options.vector.fieldPath,
+    queryEmbedding: options.vector.queryEmbedding,
+    metric: options.vector.metric ?? "cosine",
+    limit: vectorK,
+    ...options.vector.minScore === void 0 ? {} : { minScore: options.vector.minScore }
+  });
+  const fulltextPromise = backend.fulltextSearch({
+    graphId,
+    nodeKind,
+    query: options.fulltext.query,
+    limit: fulltextK,
+    ...options.fulltext.mode ? { mode: options.fulltext.mode } : {},
+    ...options.fulltext.language ? { language: options.fulltext.language } : {},
+    ...options.fulltext.minScore === void 0 ? {} : { minScore: options.fulltext.minScore },
+    ...options.fulltext.includeSnippets === void 0 ? {} : { includeSnippets: options.fulltext.includeSnippets }
+  });
+  const [vectorRows, fulltextRows] = await Promise.all([
+    vectorPromise,
+    fulltextPromise
+  ]);
+  const fused = /* @__PURE__ */ new Map();
+  for (const [index, row] of vectorRows.entries()) {
+    const rank2 = index + 1;
+    const contribution = vectorWeight / (fusionK + rank2);
+    const entry = fused.get(row.nodeId) ?? {
+      nodeId: row.nodeId,
+      fusedScore: 0
+    };
+    entry.fusedScore += contribution;
+    entry.vectorRank = rank2;
+    entry.vectorScore = row.score;
+    fused.set(row.nodeId, entry);
+  }
+  for (const [index, row] of fulltextRows.entries()) {
+    const rank2 = index + 1;
+    const contribution = fulltextWeight / (fusionK + rank2);
+    const entry = fused.get(row.nodeId) ?? {
+      nodeId: row.nodeId,
+      fusedScore: 0
+    };
+    entry.fusedScore += contribution;
+    entry.fulltextRank = rank2;
+    entry.fulltextScore = row.score;
+    if (row.snippet !== void 0) {
+      entry.fulltextSnippet = row.snippet;
+    }
+    fused.set(row.nodeId, entry);
+  }
+  const ranked = [...fused.values()].toSorted(
+    (a, b) => b.fusedScore - a.fusedScore || a.nodeId.localeCompare(b.nodeId)
+  ).slice(0, options.limit);
+  const ids = ranked.map((entry) => entry.nodeId);
+  const nodeMap = await fetchNodesByIds(backend, graphId, nodeKind, ids);
+  const hits = [];
+  let rank = 1;
+  for (const entry of ranked) {
+    const node = nodeMap.get(entry.nodeId);
+    if (!node) continue;
+    const typedNode = node;
+    const hit = {
+      node: typedNode,
+      score: entry.fusedScore,
+      rank,
+      ...entry.vectorRank !== void 0 && entry.vectorScore !== void 0 ? {
+        vector: {
+          node: typedNode,
+          score: entry.vectorScore,
+          rank: entry.vectorRank
+        }
+      } : {},
+      ...entry.fulltextRank !== void 0 && entry.fulltextScore !== void 0 ? {
+        fulltext: {
+          node: typedNode,
+          score: entry.fulltextScore,
+          rank: entry.fulltextRank,
+          ...entry.fulltextSnippet === void 0 ? {} : { snippet: entry.fulltextSnippet }
+        }
+      } : {}
+    };
+    hits.push(hit);
+    rank += 1;
+  }
+  return hits;
+}
+function validateFulltextCallOptions(backend, options) {
+  const strategy = backend.fulltextStrategy;
+  const capabilities = backend.capabilities.fulltext;
+  if (options.mode !== void 0) {
+    validateFulltextMode(backend, strategy, capabilities, options.mode);
+  }
+  if (options.includeSnippets === true) {
+    validateFulltextSnippets(backend, strategy, capabilities);
+  }
+  if (options.language !== void 0) {
+    validateFulltextLanguageOption(
+      backend,
+      strategy,
+      capabilities,
+      options.language
+    );
+  }
+}
+function validateFulltextMode(backend, strategy, capabilities, mode) {
+  if (strategy !== void 0) {
+    if (strategy.supportedModes.includes(mode)) return;
+    throw new ConfigurationError(
+      `Backend "${backend.dialect}" fulltext strategy "${strategy.name}" does not support mode "${mode}". Supported modes: ${strategy.supportedModes.join(", ")}`,
+      {
+        backend: backend.dialect,
+        strategy: strategy.name,
+        capability: `fulltext.modes.${mode}`
+      }
+    );
+  }
+  if (mode === "phrase" && capabilities && !capabilities.phraseQueries) {
+    throw new ConfigurationError(
+      `Backend "${backend.dialect}" does not support phrase queries`,
+      { backend: backend.dialect, capability: "fulltext.phraseQueries" }
+    );
+  }
+}
+function validateFulltextSnippets(backend, strategy, capabilities) {
+  const supportsSnippets = strategy === void 0 ? capabilities?.highlighting !== false : strategy.supportsSnippets;
+  if (supportsSnippets) return;
+  throw new ConfigurationError(
+    `Backend "${backend.dialect}" does not support snippet highlighting; drop includeSnippets or switch to a backend where highlighting is supported`,
+    { backend: backend.dialect, capability: "fulltext.highlighting" }
+  );
+}
+function validateFulltextLanguageOption(backend, strategy, capabilities, language) {
+  if (strategy !== void 0 && !strategy.supportsLanguageOverride) {
+    throw new ConfigurationError(
+      `Backend "${backend.dialect}" fulltext strategy "${strategy.name}" does not honor a per-query \`language\` override (its tokenizer is fixed at table-create time). Drop the option, or pick a strategy that advertises \`supportsLanguageOverride: true\`.`,
+      {
+        backend: backend.dialect,
+        strategy: strategy.name,
+        capability: "fulltext.languageOverride"
+      }
+    );
+  }
+  if (capabilities !== void 0) {
+    warnIfLanguageNotAdvertised(backend.dialect, capabilities, language);
+  }
+}
+function warnIfLanguageNotAdvertised(dialect, capabilities, language) {
+  if (capabilities.languages.length === 0) return;
+  if (capabilities.languages.includes(language)) return;
+  if (typeof console === "undefined" || typeof console.warn !== "function") {
+    return;
+  }
+  console.warn(
+    `[typegraph] fulltext language "${language}" is not in the advertised list for dialect "${dialect}" (${capabilities.languages.join(", ")}). If your backend has this language installed this warning is safe to ignore.`
+  );
+}
+async function fetchNodesByIds(backend, graphId, nodeKind, ids) {
+  if (ids.length === 0) return /* @__PURE__ */ new Map();
+  const map = /* @__PURE__ */ new Map();
+  if (backend.getNodes) {
+    const rows = await backend.getNodes(graphId, nodeKind, ids);
+    for (const row of rows) {
+      if (row.deleted_at !== void 0) continue;
+      map.set(row.id, rowToNode(row));
+    }
+    return map;
+  }
+  for (const id of ids) {
+    const row = await backend.getNode(graphId, nodeKind, id);
+    if (row && row.deleted_at === void 0) map.set(row.id, rowToNode(row));
+  }
+  return map;
+}
+
+// src/store/search-facade.ts
+var StoreSearch = class {
+  #context;
+  constructor(context) {
+    this.#context = context;
+  }
+  /**
+   * 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.
+   */
+  async fulltext(nodeKind, options) {
+    return executeFulltextSearch(
+      { graphId: this.#context.graphId, backend: this.#context.backend },
+      nodeKind,
+      options
+    );
+  }
+  /**
+   * 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.
+   */
+  async hybrid(nodeKind, options) {
+    return executeHybridSearch(
+      { graphId: this.#context.graphId, backend: this.#context.backend },
+      nodeKind,
+      options
+    );
+  }
+  /**
+   * 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.
+   */
+  async rebuildFulltext(nodeKind, options = {}) {
+    return rebuildFulltextIndex(
+      {
+        graphId: this.#context.graphId,
+        backend: this.#context.backend,
+        registry: this.#context.registry
+      },
+      nodeKind,
+      options
+    );
+  }
+};
+
 // src/store/store.ts
 var Store = class {
   #graph;
@@ -11987,6 +13138,7 @@ var Store = class {
   #nodeCollections;
   #edgeCollections;
   #algorithms;
+  #search;
   constructor(graph, backend, options) {
     this.#graph = graph;
     this.#backend = backend;
@@ -12235,6 +13387,44 @@ var Store = class {
   query() {
     return this.#createQueryForBackend(this.#backend);
   }
+  // === Search ===
+  /**
+   * 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() {
+    if (this.#search === void 0) {
+      this.#search = new StoreSearch({
+        graphId: this.graphId,
+        backend: this.#backend,
+        registry: this.#registry
+      });
+    }
+    return this.#search;
+  }
   // === Batch Query Execution ===
   /**
    * Executes multiple queries over a single connection with snapshot consistency.
@@ -12379,6 +13569,7 @@ var Store = class {
     this.#nodeCollections = void 0;
     this.#edgeCollections = void 0;
     this.#algorithms = void 0;
+    this.#search = void 0;
   }
   // === Lifecycle ===
   /**
@@ -12485,6 +13676,6 @@ async function createStoreWithSchema(graph, backend, options) {
   return [store, result];
 }
 
-export { DEFAULT_SQL_SCHEMA, ExecutableAggregateQuery, ExecutableQuery, MAX_EXPLICIT_RECURSIVE_DEPTH, MAX_RECURSIVE_DEPTH, PreparedQuery, QueryBuilder, UnionableQuery, avg, broader, composeFragments, core, count, countDistinct, createExternalRef, createFragment, createQueryBuilder, createSqlSchema, createStore, createStoreWithSchema, defineEdge, defineNode, defineSubgraphProject, differentFrom, disjointWith, equivalentTo, exists, externalRef, field, fieldRef, generateId, getExternalRefTable, hasPart, having, havingEq, havingGt, havingGte, havingLt, havingLte, implies, inSubquery, inverseOf, isExternalRefSchema, isParameterRef, limitFragment, max, metaEdge, min, narrower, notExists, notInSubquery, offsetFragment, orderByFragment, param, partOf, relatedTo, sameAs, subClassOf, sum };
+export { DEFAULT_SQL_SCHEMA, ExecutableAggregateQuery, ExecutableQuery, MAX_EXPLICIT_RECURSIVE_DEPTH, MAX_RECURSIVE_DEPTH, PreparedQuery, QueryBuilder, StoreSearch, UnionableQuery, avg, broader, composeFragments, core, count, countDistinct, createExternalRef, createFragment, createQueryBuilder, createSqlSchema, createStore, createStoreWithSchema, defineEdge, defineNode, defineSubgraphProject, differentFrom, disjointWith, equivalentTo, exists, externalRef, field, fieldRef, generateId, getExternalRefTable, hasPart, having, havingEq, havingGt, havingGte, havingLt, havingLte, implies, inSubquery, inverseOf, isExternalRefSchema, isParameterRef, limitFragment, max, metaEdge, min, narrower, notExists, notInSubquery, offsetFragment, orderByFragment, param, partOf, relatedTo, sameAs, subClassOf, sum };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map