@reftrixmcp/ml 0.1.7

package/dist/embeddings/worker-thread.js

@@ -0,0 +1,441 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * ONNX Embedding Worker Thread
+ *
+ * Runs ONNX inference in a separate thread so CPU-bound inference
+ * does not block the main thread's event loop. This allows BullMQ
+ * heartbeats, IPC messages, and other async operations to proceed
+ * while inference is in progress.
+ *
+ * Architecture:
+ * - Main thread sends prefixed texts via parentPort messages.
+ * - This worker owns the entire ONNX pipeline lifecycle
+ *   (init, inference, recycle, dispose).
+ * - Results are sent back as plain number[][] (structured clone safe).
+ * - ONNX Session/Tensor objects never cross thread boundaries.
+ *
+ * @module embeddings/worker-thread
+ */
+import { parentPort } from "node:worker_threads";
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import nodePath from "node:path";
+/**
+ * Detect the ONNX execution provider based on environment configuration.
+ *
+ * Checks ONNX_EXECUTION_PROVIDER env var and verifies that the CUDA
+ * provider shared library is available on disk. Falls back to CPU
+ * gracefully if the provider is not installed.
+ */
+function detectExecutionProvider() {
+    const envProvider = process.env.ONNX_EXECUTION_PROVIDER;
+    if (envProvider === "cuda" || envProvider === "rocm") {
+        const cudaAvailable = verifyCudaAvailability();
+        if (cudaAvailable) {
+            return "cuda";
+        }
+        console.warn("[EmbeddingWorker] ONNX_EXECUTION_PROVIDER=%s but CUDA provider not available, falling back to CPU", envProvider);
+        return "cpu";
+    }
+    return "cpu";
+}
+/**
+ * Verify that CUDA provider (libonnxruntime_providers_cuda.so) is available.
+ *
+ * onnxruntime-node can download the CUDA provider shared library via
+ * `ONNXRUNTIME_NODE_INSTALL_CUDA=v12 node .../install.js`. This function
+ * checks for its presence on disk rather than trying to resolve a
+ * non-existent npm package (onnxruntime-gpu is Python-only).
+ */
+function verifyCudaAvailability() {
+    try {
+        const esmRequire = createRequire(import.meta.url);
+        const ortNodePath = esmRequire.resolve("onnxruntime-node");
+        // require.resolve returns e.g. .../onnxruntime-node/dist/index.js
+        // Walk up to package root by finding the directory containing package.json
+        let packageDir = nodePath.dirname(ortNodePath);
+        for (let i = 0; i < 5; i++) {
+            if (fs.existsSync(nodePath.join(packageDir, "package.json")))
+                break;
+            packageDir = nodePath.dirname(packageDir);
+        }
+        // Search across napi versions (v3, v6, etc.) for CUDA provider
+        const binDir = nodePath.join(packageDir, "bin");
+        if (fs.existsSync(binDir)) {
+            const napiDirs = fs.readdirSync(binDir).filter((d) => d.startsWith("napi-v"));
+            for (const napiDir of napiDirs) {
+                const cudaProviderPath = nodePath.join(binDir, napiDir, "linux", "x64", "libonnxruntime_providers_cuda.so");
+                if (fs.existsSync(cudaProviderPath)) {
+                    return true;
+                }
+            }
+        }
+        console.warn("[EmbeddingWorker] CUDA provider not found in: %s", binDir);
+        return false;
+    }
+    catch {
+        console.warn("[EmbeddingWorker] Cannot verify CUDA provider: onnxruntime-node not found");
+        return false;
+    }
+}
+// =====================================================
+// Worker state
+// =====================================================
+let pipeline = null;
+let initPromise = null;
+let inferencesSinceRecycle = 0;
+let totalRecycles = 0;
+let resolvedProvider = "cpu";
+/** Whether resolvedProvider was explicitly set by a switch-provider message. */
+let providerExplicitlySet = false;
+let config = {
+    modelId: "Xenova/multilingual-e5-base",
+    cacheDir: "./.cache/models",
+    device: "cpu",
+    dtype: "fp32",
+    pipelineRecycleThreshold: 30,
+};
+const EMBEDDING_DIMENSION = 768;
+// =====================================================
+// Pipeline management
+// =====================================================
+function normalizeVector(vector) {
+    const norm = Math.sqrt(vector.reduce((sum, val) => sum + val * val, 0));
+    if (norm === 0)
+        return vector;
+    return vector.map((val) => val / norm);
+}
+/**
+ * Verify that LD_LIBRARY_PATH is set at the OS level (not just process.env).
+ *
+ * dlopen() reads LD_LIBRARY_PATH from the kernel environment (/proc/self/environ),
+ * NOT from process.env modifications made at runtime. If LD_LIBRARY_PATH was set
+ * after process startup (e.g. by loadEnvLocal()), dlopen() cannot find CUDA
+ * libraries and ONNX Runtime CUDA provider initialization will segfault or throw.
+ *
+ * Returns true only if LD_LIBRARY_PATH was present in the original process environment.
+ */
+function isLdLibraryPathSetAtOsLevel() {
+    try {
+        const procEnv = fs.readFileSync("/proc/self/environ", "utf-8");
+        return procEnv.includes("LD_LIBRARY_PATH");
+    }
+    catch {
+        // /proc/self/environ not available (non-Linux) — assume set
+        return true;
+    }
+}
+async function initializePipeline() {
+    if (pipeline)
+        return;
+    if (initPromise)
+        return initPromise;
+    initPromise = (async () => {
+        try {
+            // Only auto-detect from env on first init. If provider was explicitly
+            // set by a switch-provider message, respect that setting.
+            if (!providerExplicitlySet) {
+                resolvedProvider = detectExecutionProvider();
+            }
+            // Safety check: if CUDA is requested but LD_LIBRARY_PATH was not set at
+            // the OS level (only set via loadEnvLocal at runtime), CUDA init will crash
+            // because dlopen() can't find CUDA shared libraries. Fall back to CPU.
+            if (resolvedProvider === "cuda" && !isLdLibraryPathSetAtOsLevel()) {
+                console.warn("[EmbeddingWorker] CUDA requested but LD_LIBRARY_PATH not set at OS level. " +
+                    "dlopen() cannot find CUDA libraries. Falling back to CPU. " +
+                    "To use CUDA, set LD_LIBRARY_PATH before starting the Node.js process.");
+                resolvedProvider = "cpu";
+            }
+            const effectiveDevice = resolvedProvider === "cuda" ? "cuda" : config.device;
+            // eslint-disable-next-line no-console
+            console.log("[EmbeddingWorker] Initializing ONNX pipeline", {
+                model: config.modelId,
+                requestedDevice: config.device,
+                resolvedProvider,
+                effectiveDevice,
+                dtype: config.dtype,
+                recycleThreshold: config.pipelineRecycleThreshold,
+            });
+            const { pipeline: createPipeline } = await import("@huggingface/transformers");
+            // Attempt to create pipeline with the resolved device.
+            // If CUDA init fails (e.g. library not found), catch and retry with CPU.
+            try {
+                pipeline = (await createPipeline("feature-extraction", config.modelId, {
+                    dtype: config.dtype,
+                    device: effectiveDevice,
+                }));
+            }
+            catch (deviceError) {
+                if (effectiveDevice !== "cpu") {
+                    // CUDA/GPU init failed — fallback to CPU
+                    const deviceErrorMsg = deviceError instanceof Error ? deviceError.message : String(deviceError);
+                    console.warn("[EmbeddingWorker] %s pipeline creation failed, falling back to CPU: %s", effectiveDevice, deviceErrorMsg);
+                    resolvedProvider = "cpu";
+                    pipeline = (await createPipeline("feature-extraction", config.modelId, {
+                        dtype: config.dtype,
+                        device: "cpu",
+                    }));
+                }
+                else {
+                    throw deviceError;
+                }
+            }
+            // eslint-disable-next-line no-console
+            console.log("[EmbeddingWorker] ONNX pipeline ready (provider: %s)", resolvedProvider);
+        }
+        catch (error) {
+            initPromise = null;
+            const message = error instanceof Error ? error.message : "Unknown error";
+            throw new Error(`Failed to load embedding model in worker thread: ${message}`);
+        }
+    })();
+    return initPromise;
+}
+async function disposePipeline() {
+    if (pipeline && typeof pipeline.dispose === "function") {
+        try {
+            await pipeline.dispose();
+        }
+        catch {
+            // Disposal failure should not break the workflow
+        }
+    }
+    pipeline = null;
+    initPromise = null;
+    inferencesSinceRecycle = 0;
+}
+async function recyclePipelineIfNeeded(inferenceCount) {
+    inferencesSinceRecycle += inferenceCount;
+    const threshold = config.pipelineRecycleThreshold;
+    if (threshold <= 0)
+        return;
+    if (inferencesSinceRecycle >= threshold) {
+        await disposePipeline();
+        totalRecycles++;
+        if (typeof global.gc === "function") {
+            global.gc();
+        }
+    }
+}
+// =====================================================
+// Inference functions
+// =====================================================
+/**
+ * Extract number[] from a pipeline output, disposing the tensor.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractSingleEmbedding(output) {
+    let embedding;
+    if (output && typeof output.tolist === "function") {
+        const result = output.tolist();
+        embedding = Array.isArray(result[0]) ? result[0] : result;
+        if (typeof output.dispose === "function") {
+            output.dispose();
+        }
+    }
+    else if (Array.isArray(output)) {
+        embedding = output;
+    }
+    else {
+        throw new Error("Unexpected embedding output format");
+    }
+    if (embedding.length !== EMBEDDING_DIMENSION) {
+        // Non-fatal: warn but continue
+    }
+    return normalizeVector(embedding);
+}
+/**
+ * Extract number[][] from a batch pipeline output, disposing the tensor.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractBatchEmbeddings(output) {
+    let batchEmbeddings;
+    if (output && typeof output.tolist === "function") {
+        batchEmbeddings = output.tolist();
+        if (typeof output.dispose === "function") {
+            output.dispose();
+        }
+    }
+    else if (Array.isArray(output)) {
+        batchEmbeddings = output;
+    }
+    else {
+        throw new Error("Unexpected batch embedding output format");
+    }
+    return batchEmbeddings.map(normalizeVector);
+}
+async function generateSingle(text) {
+    await initializePipeline();
+    if (!pipeline)
+        throw new Error("Pipeline not initialized");
+    const output = await pipeline(text, { pooling: "mean", normalize: true });
+    const embedding = extractSingleEmbedding(output);
+    await recyclePipelineIfNeeded(1);
+    return embedding;
+}
+async function generateBatch(texts) {
+    if (texts.length === 0)
+        return [];
+    const BATCH_SIZE = 32;
+    const allEmbeddings = [];
+    for (let batchStart = 0; batchStart < texts.length; batchStart += BATCH_SIZE) {
+        const batchEnd = Math.min(batchStart + BATCH_SIZE, texts.length);
+        const batch = texts.slice(batchStart, batchEnd);
+        // Re-initialize if recycled during previous batch
+        await initializePipeline();
+        if (!pipeline)
+            throw new Error("Pipeline not initialized after recycle");
+        const output = await pipeline(batch, { pooling: "mean", normalize: true });
+        const batchEmbeddings = extractBatchEmbeddings(output);
+        allEmbeddings.push(...batchEmbeddings);
+        await recyclePipelineIfNeeded(batch.length);
+    }
+    return allEmbeddings;
+}
+// =====================================================
+// Message handler
+// =====================================================
+function sendResponse(response) {
+    parentPort?.postMessage(response);
+}
+function sendError(requestId, originalType, error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const response = {
+        type: "error",
+        requestId,
+        success: false,
+        error: errorMessage,
+        originalType,
+    };
+    parentPort?.postMessage(response);
+}
+async function handleMessage(message) {
+    switch (message.type) {
+        case "init": {
+            config = { ...config, ...message.config };
+            const startTime = Date.now();
+            await initializePipeline();
+            sendResponse({
+                type: "init",
+                requestId: message.requestId,
+                success: true,
+                loadTimeMs: Date.now() - startTime,
+                executionProvider: resolvedProvider,
+            });
+            break;
+        }
+        case "generate": {
+            const startTime = Date.now();
+            const embedding = await generateSingle(message.text);
+            sendResponse({
+                type: "generate",
+                requestId: message.requestId,
+                success: true,
+                embedding,
+                inferenceTimeMs: Date.now() - startTime,
+            });
+            break;
+        }
+        case "generateBatch": {
+            const startTime = Date.now();
+            const embeddings = await generateBatch(message.texts);
+            sendResponse({
+                type: "generateBatch",
+                requestId: message.requestId,
+                success: true,
+                embeddings,
+                inferenceTimeMs: Date.now() - startTime,
+            });
+            break;
+        }
+        case "dispose": {
+            await disposePipeline();
+            sendResponse({
+                type: "dispose",
+                requestId: message.requestId,
+                success: true,
+            });
+            break;
+        }
+        case "terminate": {
+            await disposePipeline();
+            sendResponse({
+                type: "terminate",
+                requestId: message.requestId,
+                success: true,
+            });
+            // Allow the response to be flushed before exiting
+            setTimeout(() => process.exit(0), 50);
+            break;
+        }
+        case "switch-provider": {
+            const targetProvider = message.provider;
+            // If switching to CUDA, verify availability first
+            if (targetProvider === "cuda") {
+                const canUseCuda = verifyCudaAvailability();
+                if (!canUseCuda) {
+                    // Cannot switch to CUDA — respond with current (cpu) provider
+                    sendResponse({
+                        type: "switch-provider",
+                        requestId: message.requestId,
+                        success: true,
+                        provider: "cpu",
+                    });
+                    break;
+                }
+            }
+            // Dispose current pipeline before switching
+            await disposePipeline();
+            // Update provider and config — mark as explicitly set so
+            // initializePipeline() won't override via detectExecutionProvider()
+            resolvedProvider = targetProvider;
+            providerExplicitlySet = true;
+            config = { ...config, device: targetProvider };
+            // eslint-disable-next-line no-console
+            console.log("[EmbeddingWorker] Switched provider to:", resolvedProvider);
+            sendResponse({
+                type: "switch-provider",
+                requestId: message.requestId,
+                success: true,
+                provider: resolvedProvider,
+            });
+            break;
+        }
+        case "release-gpu": {
+            // Dispose pipeline and revert to CPU
+            await disposePipeline();
+            resolvedProvider = "cpu";
+            providerExplicitlySet = true;
+            config = { ...config, device: "cpu" };
+            // eslint-disable-next-line no-console
+            console.log("[EmbeddingWorker] Released GPU, reverted to CPU");
+            sendResponse({
+                type: "release-gpu",
+                requestId: message.requestId,
+                success: true,
+            });
+            break;
+        }
+        default: {
+            // SEC-M2: Reject unknown message types for defense-in-depth
+            const unknownType = message.type ?? "unknown";
+            sendError(message.requestId ?? "unknown", unknownType, new Error(`Unknown worker message type: ${String(unknownType)}`));
+            break;
+        }
+    }
+}
+// =====================================================
+// Setup parentPort listener
+// =====================================================
+if (!parentPort) {
+    throw new Error("worker-thread.ts must be run as a Worker Thread (no parentPort)");
+}
+parentPort.on("message", (message) => {
+    handleMessage(message).catch((error) => {
+        sendError(message.requestId, message.type, error);
+    });
+});
+// Export recycle count for monitoring (accessible via workerData if needed)
+export { totalRecycles, inferencesSinceRecycle };
+//# sourceMappingURL=worker-thread.js.map

package/dist/embeddings/worker-thread.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-thread.js","sourceRoot":"","sources":["../../src/embeddings/worker-thread.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @reftrixmcp/ml
+ * ML/Embedding and Search services for Reftrix
+ */
+export { EmbeddingService, embeddingService, cosineSimilarity } from "./embeddings/index.js";
+export type { EmbeddingTextType, EmbeddingServiceConfig, CacheStats, EmbeddingResult, BatchEmbeddingResult, } from "./embeddings/index.js";
+export { StyleEmbeddingService, styleEmbeddingService, createStyleEmbedding, createBatchStyleEmbeddings, createQueryEmbedding, } from "./embeddings/index.js";
+export type { StyleEmbeddingConfig } from "./embeddings/index.js";
+export { VisionEmbeddingService, visionEmbeddingService, createVisionEmbedding, createBatchVisionEmbeddings, visionFeaturesToText, } from "./embeddings/index.js";
+export type { VisionFeatures, VisionRhythm, VisionDensity, VisionGravity, VisionTheme, VisionEmbeddingServiceConfig, VisionCacheStats, } from "./embeddings/index.js";
+export { DINOv2Service, DINOV2_EMBEDDING_DIMENSION, DINOV2_INPUT_SIZE } from "./dinov2/index.js";
+export type { DINOv2ServiceConfig } from "./dinov2/index.js";
+export type { DINOv2WorkerMessage, DINOv2WorkerResponse } from "./dinov2/index.js";
+export { calculateRRF, mergeWithRRF, normalizeRRFScore, toRankedItems } from "./search/index.js";
+export { executeHybridSearch } from "./search/index.js";
+export { buildFulltextConditions, buildFulltextRankExpression } from "./search/index.js";
+export type { SearchFilters, SearchOptions, HybridSearchOptions, SearchResult, SummarySearchResult, SearchResultItem, SummarySearchResultItem, VectorSearchRawResult, FullTextSearchRawResult, RankedItem, RRFScoredItem, HybridSearchConfig, HybridSearchResult, } from "./search/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;;GAGG;AAGH,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC7F,YAAY,EACV,iBAAiB,EACjB,sBAAsB,EACtB,UAAU,EACV,eAAe,EACf,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,0BAA0B,EAC1B,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAGlE,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,EACrB,2BAA2B,EAC3B,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,cAAc,EACd,YAAY,EACZ,aAAa,EACb,aAAa,EACb,WAAW,EACX,4BAA4B,EAC5B,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,aAAa,EAAE,0BAA0B,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACjG,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,YAAY,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAGnF,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACjG,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AACzF,YAAY,EACV,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,EAChB,uBAAuB,EACvB,qBAAqB,EACrB,uBAAuB,EACvB,UAAU,EACV,aAAa,EACb,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * @reftrixmcp/ml
+ * ML/Embedding and Search services for Reftrix
+ */
+// Embedding service exports
+export { EmbeddingService, embeddingService, cosineSimilarity } from "./embeddings/index.js";
+// Style Feature Embedding exports
+export { StyleEmbeddingService, styleEmbeddingService, createStyleEmbedding, createBatchStyleEmbeddings, createQueryEmbedding, } from "./embeddings/index.js";
+// Vision Feature Embedding exports
+export { VisionEmbeddingService, visionEmbeddingService, createVisionEmbedding, createBatchVisionEmbeddings, visionFeaturesToText, } from "./embeddings/index.js";
+// DINOv2 visual embedding exports
+export { DINOv2Service, DINOV2_EMBEDDING_DIMENSION, DINOV2_INPUT_SIZE } from "./dinov2/index.js";
+// Search utilities exports (SearchService removed in v0.1.0)
+export { calculateRRF, mergeWithRRF, normalizeRRFScore, toRankedItems } from "./search/index.js";
+export { executeHybridSearch } from "./search/index.js";
+export { buildFulltextConditions, buildFulltextRankExpression } from "./search/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,yCAAyC;AAEzC;;;GAGG;AAEH,4BAA4B;AAC5B,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAS7F,kCAAkC;AAClC,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,0BAA0B,EAC1B,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAG/B,mCAAmC;AACnC,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,EACrB,2BAA2B,EAC3B,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAW/B,kCAAkC;AAClC,OAAO,EAAE,aAAa,EAAE,0BAA0B,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAIjG,6DAA6D;AAC7D,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACjG,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/search/fulltext-helpers.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Full-text search SQL helpers for Hybrid Search.
+ *
+ * Provides shared SQL clause builders used across layout, motion,
+ * background, and narrative hybrid search implementations.
+ *
+ * @see TDA-HS-R2: DRY principle for fulltext SQL construction
+ */
+/**
+ * Build WHERE conditions for PostgreSQL tsvector full-text search.
+ *
+ * Generates the standard three-part condition:
+ * 1. search_vector IS NOT NULL
+ * 2. plainto_tsquery('english', $N) <> ''::tsquery  (skip empty queries)
+ * 3. search_vector @@ plainto_tsquery('english', $N) (actual match)
+ *
+ * @param searchVectorColumn - Fully qualified column name (e.g., 'se.search_vector')
+ * @param paramIndex - The $N parameter index for the query text
+ * @returns SQL condition string (without leading AND/WHERE)
+ */
+export declare function buildFulltextConditions(searchVectorColumn: string, paramIndex: number): string;
+/**
+ * Build ts_rank_cd expression for full-text search ranking.
+ *
+ * @param searchVectorColumn - Fully qualified column name (e.g., 'se.search_vector')
+ * @param paramIndex - The $N parameter index for the query text
+ * @returns SQL expression string for use in SELECT or ORDER BY
+ */
+export declare function buildFulltextRankExpression(searchVectorColumn: string, paramIndex: number): string;
+//# sourceMappingURL=fulltext-helpers.d.ts.map

package/dist/search/fulltext-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fulltext-helpers.d.ts","sourceRoot":"","sources":["../../src/search/fulltext-helpers.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,kBAAkB,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAM9F;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,kBAAkB,EAAE,MAAM,EAC1B,UAAU,EAAE,MAAM,GACjB,MAAM,CAER"}

package/dist/search/fulltext-helpers.js

@@ -0,0 +1,40 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Full-text search SQL helpers for Hybrid Search.
+ *
+ * Provides shared SQL clause builders used across layout, motion,
+ * background, and narrative hybrid search implementations.
+ *
+ * @see TDA-HS-R2: DRY principle for fulltext SQL construction
+ */
+/**
+ * Build WHERE conditions for PostgreSQL tsvector full-text search.
+ *
+ * Generates the standard three-part condition:
+ * 1. search_vector IS NOT NULL
+ * 2. plainto_tsquery('english', $N) <> ''::tsquery  (skip empty queries)
+ * 3. search_vector @@ plainto_tsquery('english', $N) (actual match)
+ *
+ * @param searchVectorColumn - Fully qualified column name (e.g., 'se.search_vector')
+ * @param paramIndex - The $N parameter index for the query text
+ * @returns SQL condition string (without leading AND/WHERE)
+ */
+export function buildFulltextConditions(searchVectorColumn, paramIndex) {
+    return [
+        `${searchVectorColumn} IS NOT NULL`,
+        `plainto_tsquery('english', $${paramIndex}) <> ''::tsquery`,
+        `${searchVectorColumn} @@ plainto_tsquery('english', $${paramIndex})`,
+    ].join(" AND ");
+}
+/**
+ * Build ts_rank_cd expression for full-text search ranking.
+ *
+ * @param searchVectorColumn - Fully qualified column name (e.g., 'se.search_vector')
+ * @param paramIndex - The $N parameter index for the query text
+ * @returns SQL expression string for use in SELECT or ORDER BY
+ */
+export function buildFulltextRankExpression(searchVectorColumn, paramIndex) {
+    return `ts_rank_cd(${searchVectorColumn}, plainto_tsquery('english', $${paramIndex}))`;
+}
+//# sourceMappingURL=fulltext-helpers.js.map

package/dist/search/fulltext-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fulltext-helpers.js","sourceRoot":"","sources":["../../src/search/fulltext-helpers.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,yCAAyC;AAEzC;;;;;;;GAOG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CAAC,kBAA0B,EAAE,UAAkB;IACpF,OAAO;QACL,GAAG,kBAAkB,cAAc;QACnC,+BAA+B,UAAU,kBAAkB;QAC3D,GAAG,kBAAkB,mCAAmC,UAAU,GAAG;KACtE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B,CACzC,kBAA0B,EAC1B,UAAkB;IAElB,OAAO,cAAc,kBAAkB,iCAAiC,UAAU,IAAI,CAAC;AACzF,CAAC"}

package/dist/search/hybrid.d.ts

@@ -0,0 +1,40 @@
+import type { RankedItem } from "./rrf.js";
+/**
+ * Configuration for hybrid search execution
+ */
+export interface HybridSearchConfig {
+    /** Weight for vector search results (default 0.6) */
+    vectorWeight?: number;
+    /** Weight for full-text search results (default 0.4) */
+    fulltextWeight?: number;
+    /** RRF constant k (default 60) */
+    k?: number;
+}
+/**
+ * Result from hybrid search with normalized similarity score
+ */
+export interface HybridSearchResult {
+    id: string;
+    /** Normalized similarity score (0-1) */
+    similarity: number;
+    /** Source information for debugging */
+    source: {
+        vectorRank?: number;
+        fulltextRank?: number;
+    };
+    /** Additional data from the search result */
+    data: Record<string, unknown>;
+}
+/**
+ * Execute hybrid search by combining vector and full-text search results with RRF
+ *
+ * Both search functions are executed in parallel via Promise.all for minimum latency.
+ * Results are merged using Reciprocal Rank Fusion (RRF) with configurable weights.
+ *
+ * @param vectorSearchFn - Function that returns vector search results (ranked by cosine similarity)
+ * @param fulltextSearchFn - Function that returns full-text search results (ranked by ts_rank_cd)
+ * @param config - Optional hybrid search configuration
+ * @returns Merged results sorted by normalized RRF similarity score
+ */
+export declare function executeHybridSearch(vectorSearchFn: () => Promise<RankedItem[]>, fulltextSearchFn: () => Promise<RankedItem[]>, config?: HybridSearchConfig): Promise<HybridSearchResult[]>;
+//# sourceMappingURL=hybrid.d.ts.map

package/dist/search/hybrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid.d.ts","sourceRoot":"","sources":["../../src/search/hybrid.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,UAAU,EAAiB,MAAM,UAAU,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,MAAM,EAAE;QACN,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAQD;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,cAAc,EAAE,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC,EAC3C,gBAAgB,EAAE,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC,EAC7C,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,kBAAkB,EAAE,CAAC,CA0C/B"}