@agent-native/core 0.111.3 → 0.112.0

package/corpus/core/src/coding-tools/index.ts

@@ -451,7 +451,11 @@ export async function runCodingCommand(
   command: string,
   cwd: string,
   timeoutMs: number,
-  options: { stdin?: string; onChunk?: BashOutputChunkCallback } = {},
+  options: {
+    stdin?: string;
+    onChunk?: BashOutputChunkCallback;
+    signal?: AbortSignal;
+  } = {},
 ): Promise<CodingCommandResult> {
   const child = spawn(command, {
     cwd,
@@ -463,9 +467,10 @@ export async function runCodingCommand(
   let stderr = "";
   let timedOut = false;
   const startMs = Date.now();
+  const abort = () => child.kill("SIGTERM");
   const timer = setTimeout(() => {
     timedOut = true;
-    child.kill("SIGTERM");
+    abort();
   }, timeoutMs);
   child.stdout?.on("data", (chunk: Buffer) => {
     const text = chunk.toString();
@@ -479,12 +484,26 @@ export async function runCodingCommand(
   });
   if (options.stdin) child.stdin?.end(options.stdin);
   else child.stdin?.end();
-  const code = await new Promise<number | null>((resolve, reject) => {
-    child.once("error", reject);
-    child.once("close", resolve);
-  });
-  clearTimeout(timer);
-  return { code, stdout, stderr, timedOut, durationMs: Date.now() - startMs };
+  if (options.signal) {
+    if (options.signal.aborted) abort();
+    else options.signal.addEventListener("abort", abort, { once: true });
+  }
+  try {
+    const code = await new Promise<number | null>((resolve, reject) => {
+      child.once("error", reject);
+      child.once("close", resolve);
+    });
+    return {
+      code,
+      stdout,
+      stderr,
+      timedOut,
+      durationMs: Date.now() - startMs,
+    };
+  } finally {
+    clearTimeout(timer);
+    options.signal?.removeEventListener("abort", abort);
+  }
 }
 
 /**

package/corpus/core/src/embeddings/index.ts

@@ -0,0 +1,233 @@
+import { readBoundedResponseBytes } from "../ingestion/index.js";
+import { resolveSecret } from "../server/credential-provider.js";
+
+export type EmbeddingInputPurpose = "query" | "document";
+export interface EmbeddingImageInput {
+  mimeType: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+  base64: string;
+}
+export interface MultimodalEmbeddingInput {
+  text?: string;
+  images?: EmbeddingImageInput[];
+}
+export interface EmbeddingFamily {
+  id: string;
+  provider: "gemini" | "cohere" | "voyage" | (string & {});
+  model: string;
+  version: string;
+  dimensions: number;
+  supportedImageMimeTypes?: readonly EmbeddingImageInput["mimeType"][];
+  embed(
+    inputs: readonly MultimodalEmbeddingInput[],
+    purpose: EmbeddingInputPurpose,
+  ): Promise<number[][]>;
+}
+
+const DEFAULT_DIMENSIONS = 1024;
+function dataUrl(image: EmbeddingImageInput) {
+  return `data:${image.mimeType};base64,${image.base64}`;
+}
+function normalizedInput(input: MultimodalEmbeddingInput) {
+  const text = input.text?.trim();
+  const images = input.images ?? [];
+  if (!text && !images.length)
+    throw new Error("Embedding input needs text, an image, or both.");
+  return { text, images };
+}
+async function postJson(
+  url: string,
+  headers: Record<string, string>,
+  body: unknown,
+  providerModel: string,
+): Promise<Record<string, unknown>> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 30_000);
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...headers },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    if (!response.ok)
+      throw new Error(
+        `Embedding provider ${providerModel} failed with status ${response.status}.`,
+      );
+    const bytes = await readBoundedResponseBytes(response, 1_000_000);
+    return JSON.parse(new TextDecoder().decode(bytes)) as Record<
+      string,
+      unknown
+    >;
+  } catch (error) {
+    if (controller.signal.aborted)
+      throw new Error(`Embedding provider ${providerModel} timed out.`);
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function numberVectors(value: unknown): number[][] {
+  if (!Array.isArray(value))
+    throw new Error("Embedding response was malformed.");
+  return value.map((vector) => {
+    if (
+      !Array.isArray(vector) ||
+      vector.some((entry) => !Number.isFinite(entry))
+    )
+      throw new Error("Embedding response contained an invalid vector.");
+    return vector.map(Number);
+  });
+}
+
+export function createGeminiEmbeddingFamily(
+  apiKey: string,
+  dimensions = DEFAULT_DIMENSIONS,
+): EmbeddingFamily {
+  const model = "gemini-embedding-2";
+  return {
+    id: `gemini:${model}:${dimensions}`,
+    provider: "gemini",
+    model,
+    version: "stable-2026-04",
+    dimensions,
+    supportedImageMimeTypes: ["image/png", "image/jpeg"],
+    async embed(inputs, purpose) {
+      const vectors: number[][] = [];
+      for (const raw of inputs) {
+        const input = normalizedInput(raw);
+        const instruction =
+          purpose === "query"
+            ? "task: search result | query:"
+            : "title: none | text:";
+        const result = await postJson(
+          `https://generativelanguage.googleapis.com/v1beta/models/${model}:embedContent`,
+          { "x-goog-api-key": apiKey },
+          {
+            content: {
+              parts: [
+                { text: `${instruction} ${input.text ?? ""}`.trim() },
+                ...input.images.map((image) => ({
+                  inlineData: { mimeType: image.mimeType, data: image.base64 },
+                })),
+              ],
+            },
+            output_dimensionality: dimensions,
+          },
+          `gemini/${model}`,
+        );
+        vectors.push(
+          ...numberVectors([
+            (result.embedding as { values?: unknown } | undefined)?.values,
+          ]),
+        );
+      }
+      return vectors;
+    },
+  };
+}
+export function createCohereEmbeddingFamily(
+  apiKey: string,
+  dimensions = DEFAULT_DIMENSIONS,
+): EmbeddingFamily {
+  const model = "embed-v4.0";
+  return {
+    id: `cohere:${model}:${dimensions}`,
+    provider: "cohere",
+    model,
+    version: "v4.0",
+    dimensions,
+    supportedImageMimeTypes: [
+      "image/png",
+      "image/jpeg",
+      "image/webp",
+      "image/gif",
+    ],
+    async embed(inputs, purpose) {
+      const result = await postJson(
+        "https://api.cohere.com/v2/embed",
+        { Authorization: `Bearer ${apiKey}` },
+        {
+          model,
+          inputs: inputs.map((raw) => {
+            const input = normalizedInput(raw);
+            return {
+              content: [
+                ...(input.text ? [{ type: "text", text: input.text }] : []),
+                ...input.images.map((image) => ({
+                  type: "image_url",
+                  image_url: { url: dataUrl(image) },
+                })),
+              ],
+            };
+          }),
+          input_type: purpose === "query" ? "search_query" : "search_document",
+          embedding_types: ["float"],
+          output_dimension: dimensions,
+        },
+        `cohere/${model}`,
+      );
+      const embeddings = result.embeddings as
+        | { float?: unknown; float_?: unknown }
+        | undefined;
+      return numberVectors(embeddings?.float ?? embeddings?.float_);
+    },
+  };
+}
+export function createVoyageEmbeddingFamily(apiKey: string): EmbeddingFamily {
+  const model = "voyage-multimodal-3.5";
+  return {
+    id: `voyage:${model}:1024`,
+    provider: "voyage",
+    model,
+    version: "3.5",
+    dimensions: 1024,
+    supportedImageMimeTypes: [
+      "image/png",
+      "image/jpeg",
+      "image/webp",
+      "image/gif",
+    ],
+    async embed(inputs, purpose) {
+      const result = await postJson(
+        "https://api.voyageai.com/v1/multimodalembeddings",
+        { Authorization: `Bearer ${apiKey}` },
+        {
+          model,
+          inputs: inputs.map((raw) => {
+            const input = normalizedInput(raw);
+            return {
+              content: [
+                ...(input.text ? [{ type: "text", text: input.text }] : []),
+                ...input.images.map((image) => ({
+                  type: "image_base64",
+                  image_base64: dataUrl(image),
+                })),
+              ],
+            };
+          }),
+          input_type: purpose,
+          truncation: true,
+        },
+        `voyage/${model}`,
+      );
+      return numberVectors(result.embeddings);
+    },
+  };
+}
+export async function availableEmbeddingFamilies(): Promise<EmbeddingFamily[]> {
+  const [gemini, cohere, voyage] = await Promise.all([
+    resolveSecret("GEMINI_API_KEY").catch(() => null),
+    resolveSecret("COHERE_API_KEY").catch(() => null),
+    resolveSecret("VOYAGE_API_KEY").catch(() => null),
+  ]);
+  return [
+    ...(gemini ? [createGeminiEmbeddingFamily(gemini)] : []),
+    ...(cohere ? [createCohereEmbeddingFamily(cohere)] : []),
+    ...(voyage ? [createVoyageEmbeddingFamily(voyage)] : []),
+  ];
+}
+export function defaultEmbeddingFamily(
+  families: readonly EmbeddingFamily[],
+): EmbeddingFamily | null {
+  return families.length === 1 ? (families[0] ?? null) : null;
+}

package/corpus/core/src/index.ts

@@ -399,6 +399,8 @@ export * from "./review/index.js";
 export * from "./org-team/index.js";
 export * from "./navigation/index.js";
 export * from "./command-navigation/index.js";
+export * from "./search/index.js";
+export * from "./embeddings/index.js";
 export {
   registerWorkspaceConnectionOnboardingStep,
   type RegisterWorkspaceConnectionOnboardingStepOptions,

package/corpus/core/src/search/index.ts

@@ -0,0 +1,413 @@
+import type { DbExec } from "../db/index.js";
+import { isPostgres } from "../db/index.js";
+
+export const DEFAULT_SEARCH_NAMESPACE = "creative_context";
+export const PGVECTOR_REQUIRED_MESSAGE =
+  "Vector search requires Postgres with the pgvector extension in the configured DATABASE_URL database.";
+
+export interface SearchNamespaceIdentifiers {
+  namespace: string;
+  ftsTable: string;
+  ftsIndex: string;
+  ftsAudienceIndex: string;
+  vectorTable: string;
+  vectorIndex: string;
+  vectorAudienceIndex: string;
+}
+
+export interface PgVectorHit {
+  vectorKey: string;
+  embeddingSetId: string;
+  score: number;
+}
+
+export interface PostgresFtsHit {
+  chunkId: string;
+  itemVersionId: string;
+  score: number;
+}
+
+export interface RankedCandidate<T> {
+  key: string;
+  value: T;
+  score: number;
+  reason?: string;
+}
+
+export interface FusedCandidate<T> extends RankedCandidate<T> {
+  laneRanks: Record<string, number>;
+  reasons: string[];
+}
+
+type PgVectorOptions =
+  | boolean
+  | {
+      namespace?: string;
+      postgres?: boolean;
+      /** The caller has already provisioned this namespace and dimension. */
+      indexInitialized?: boolean;
+    };
+
+function pgVectorOptions(options: PgVectorOptions | undefined) {
+  return typeof options === "boolean" ? { postgres: options } : (options ?? {});
+}
+
+export function searchNamespaceIdentifiers(
+  namespace = DEFAULT_SEARCH_NAMESPACE,
+  dimensions?: number,
+): SearchNamespaceIdentifiers {
+  if (!/^[a-z][a-z0-9_]{0,62}$/.test(namespace)) {
+    throw new Error(
+      "Search namespace must start with a lowercase letter and contain only lowercase letters, numbers, and underscores.",
+    );
+  }
+  const suffix =
+    dimensions === undefined ? "" : `_${checkedDimensions(dimensions)}`;
+  return {
+    namespace,
+    ftsTable: `${namespace}_search_documents`,
+    ftsIndex: `${namespace}_search_documents_gin`,
+    ftsAudienceIndex: `${namespace}_search_documents_audience_gin`,
+    vectorTable: `${namespace}_vectors${suffix}`,
+    vectorIndex: `${namespace}_vectors${suffix}_hnsw`,
+    vectorAudienceIndex: `${namespace}_vectors${suffix}_audience_gin`,
+  };
+}
+
+function checkedDimensions(value: number): number {
+  if (!Number.isInteger(value) || value < 1 || value > 16_000) {
+    throw new Error("Embedding dimensions must be an integer from 1 to 16000.");
+  }
+  return value;
+}
+
+function vectorLiteral(vector: readonly number[], dimensions: number): string {
+  if (vector.length !== dimensions) {
+    throw new Error(
+      `Embedding has ${vector.length} values; expected ${dimensions}.`,
+    );
+  }
+  for (const value of vector) {
+    if (!Number.isFinite(value)) {
+      throw new Error("Embedding vectors may contain only finite numbers.");
+    }
+  }
+  return `[${vector.join(",")}]`;
+}
+
+function audienceClause(
+  audienceIds: readonly string[] | undefined,
+  column = "audience_ids",
+): { sql: string; args: string[] } {
+  if (!audienceIds?.length) return { sql: "", args: [] };
+  return {
+    sql: ` AND ${column} && ARRAY[${audienceIds.map(() => "?").join(", ")}]::TEXT[]`,
+    args: [...audienceIds],
+  };
+}
+
+export function assertPgVectorAvailable(postgres = isPostgres()): void {
+  if (!postgres) throw new Error(PGVECTOR_REQUIRED_MESSAGE);
+}
+
+export async function ensurePgVectorIndex(
+  db: DbExec,
+  dimensions: number,
+  options?: PgVectorOptions,
+): Promise<void> {
+  const resolved = pgVectorOptions(options);
+  const names = searchNamespaceIdentifiers(resolved.namespace, dimensions);
+  assertPgVectorAvailable(resolved.postgres);
+  try {
+    await db.execute("CREATE EXTENSION IF NOT EXISTS vector");
+    await db.execute(`
+      CREATE TABLE IF NOT EXISTS ${names.vectorTable} (
+        vector_key TEXT PRIMARY KEY,
+        embedding_set_id TEXT NOT NULL,
+        audience_ids TEXT[] NOT NULL DEFAULT ARRAY[]::TEXT[],
+        embedding vector(${checkedDimensions(dimensions)}) NOT NULL,
+        updated_at TEXT NOT NULL
+      )
+    `);
+    await db.execute(
+      `ALTER TABLE ${names.vectorTable} ADD COLUMN IF NOT EXISTS audience_ids TEXT[] NOT NULL DEFAULT ARRAY[]::TEXT[]`,
+    );
+    await db.execute(
+      `CREATE INDEX IF NOT EXISTS ${names.vectorIndex} ON ${names.vectorTable} USING hnsw (embedding vector_cosine_ops)`,
+    );
+    await db.execute(
+      `CREATE INDEX IF NOT EXISTS ${names.vectorAudienceIndex} ON ${names.vectorTable} USING GIN (audience_ids)`,
+    );
+  } catch (error) {
+    throw new Error(PGVECTOR_REQUIRED_MESSAGE, { cause: error });
+  }
+}
+
+export async function upsertPgVector(
+  db: DbExec,
+  input: {
+    vectorKey: string;
+    embeddingSetId: string;
+    dimensions: number;
+    vector: readonly number[];
+    audienceIds?: readonly string[];
+    updatedAt?: string;
+  },
+  options?: PgVectorOptions,
+): Promise<void> {
+  const resolved = pgVectorOptions(options);
+  const names = searchNamespaceIdentifiers(
+    resolved.namespace,
+    input.dimensions,
+  );
+  assertPgVectorAvailable(resolved.postgres);
+  if (!resolved.indexInitialized) {
+    await ensurePgVectorIndex(db, input.dimensions, resolved);
+  }
+  await db.execute({
+    sql: `
+      INSERT INTO ${names.vectorTable} (vector_key, embedding_set_id, audience_ids, embedding, updated_at)
+      VALUES (?, ?, ARRAY[${(input.audienceIds ?? []).map(() => "?").join(", ")}]::TEXT[], ?::vector, ?)
+      ON CONFLICT (vector_key) DO UPDATE SET
+        embedding_set_id = EXCLUDED.embedding_set_id,
+        audience_ids = EXCLUDED.audience_ids,
+        embedding = EXCLUDED.embedding,
+        updated_at = EXCLUDED.updated_at
+    `,
+    args: [
+      input.vectorKey,
+      input.embeddingSetId,
+      ...(input.audienceIds ?? []),
+      vectorLiteral(input.vector, input.dimensions),
+      input.updatedAt ?? new Date().toISOString(),
+    ],
+  });
+}
+
+export async function deletePgVectors(
+  db: DbExec,
+  input: {
+    dimensions: number;
+    vectorKeys: readonly string[];
+    namespace?: string;
+  },
+  postgres = isPostgres(),
+): Promise<number> {
+  const names = searchNamespaceIdentifiers(input.namespace, input.dimensions);
+  assertPgVectorAvailable(postgres);
+  if (!input.vectorKeys.length) return 0;
+  const result = await db.execute({
+    sql: `DELETE FROM ${names.vectorTable} WHERE vector_key IN (${input.vectorKeys.map(() => "?").join(", ")})`,
+    args: [...input.vectorKeys],
+  });
+  return result.rowsAffected;
+}
+
+export async function queryPgVectorIndex(
+  db: DbExec,
+  input: {
+    embeddingSetId: string;
+    dimensions: number;
+    vector: readonly number[];
+    limit?: number;
+    allowedVectorKeys?: readonly string[];
+    allowedAudienceIds?: readonly string[];
+    namespace?: string;
+  },
+  postgres = isPostgres(),
+): Promise<PgVectorHit[]> {
+  const names = searchNamespaceIdentifiers(input.namespace, input.dimensions);
+  assertPgVectorAvailable(postgres);
+  if (
+    input.allowedVectorKeys?.length === 0 ||
+    input.allowedAudienceIds?.length === 0
+  )
+    return [];
+  const limit = Math.max(1, Math.min(200, Math.floor(input.limit ?? 40)));
+  const literal = vectorLiteral(input.vector, input.dimensions);
+  const keySql = input.allowedVectorKeys?.length
+    ? ` AND vector_key IN (${input.allowedVectorKeys.map(() => "?").join(", ")})`
+    : "";
+  const audiences = audienceClause(input.allowedAudienceIds);
+  try {
+    await db.execute("SET hnsw.iterative_scan = strict_order");
+  } catch {}
+  const result = await db.execute({
+    sql: `
+      SELECT vector_key, embedding_set_id, 1 - (embedding <=> ?::vector) AS score
+      FROM ${names.vectorTable}
+      WHERE embedding_set_id = ?${keySql}${audiences.sql}
+      ORDER BY embedding <=> ?::vector
+      LIMIT ?
+    `,
+    args: [
+      literal,
+      input.embeddingSetId,
+      ...(input.allowedVectorKeys ?? []),
+      ...audiences.args,
+      literal,
+      limit,
+    ],
+  });
+  return result.rows.map((row) => ({
+    vectorKey: String(row.vector_key),
+    embeddingSetId: String(row.embedding_set_id),
+    score: Number(row.score),
+  }));
+}
+
+export async function ensurePostgresFts(
+  db: DbExec,
+  namespace = DEFAULT_SEARCH_NAMESPACE,
+): Promise<boolean> {
+  const names = searchNamespaceIdentifiers(namespace);
+  if (!isPostgres()) return false;
+  await db.execute(`
+    CREATE TABLE IF NOT EXISTS ${names.ftsTable} (
+      chunk_id TEXT PRIMARY KEY,
+      item_version_id TEXT NOT NULL,
+      audience_ids TEXT[] NOT NULL DEFAULT ARRAY[]::TEXT[],
+      document TSVECTOR NOT NULL,
+      updated_at TEXT NOT NULL
+    )
+  `);
+  await db.execute(
+    `ALTER TABLE ${names.ftsTable} ADD COLUMN IF NOT EXISTS audience_ids TEXT[] NOT NULL DEFAULT ARRAY[]::TEXT[]`,
+  );
+  await db.execute(
+    `CREATE INDEX IF NOT EXISTS ${names.ftsIndex} ON ${names.ftsTable} USING GIN (document)`,
+  );
+  await db.execute(
+    `CREATE INDEX IF NOT EXISTS ${names.ftsAudienceIndex} ON ${names.ftsTable} USING GIN (audience_ids)`,
+  );
+  return true;
+}
+
+export async function upsertPostgresFtsDocument(
+  db: DbExec,
+  input: {
+    chunkId: string;
+    itemVersionId: string;
+    title: string;
+    summary?: string | null;
+    body: string;
+    audienceIds?: readonly string[];
+    updatedAt?: string;
+    namespace?: string;
+  },
+): Promise<boolean> {
+  const namespace = input.namespace ?? DEFAULT_SEARCH_NAMESPACE;
+  if (!(await ensurePostgresFts(db, namespace))) return false;
+  const names = searchNamespaceIdentifiers(namespace);
+  await db.execute({
+    sql: `
+      INSERT INTO ${names.ftsTable} (chunk_id, item_version_id, audience_ids, document, updated_at)
+      VALUES (?, ?, ARRAY[${(input.audienceIds ?? []).map(() => "?").join(", ")}]::TEXT[], setweight(to_tsvector('simple', ?), 'A') || setweight(to_tsvector('simple', ?), 'B') || setweight(to_tsvector('simple', ?), 'C'), ?)
+      ON CONFLICT (chunk_id) DO UPDATE SET item_version_id = EXCLUDED.item_version_id, audience_ids = EXCLUDED.audience_ids, document = EXCLUDED.document, updated_at = EXCLUDED.updated_at
+    `,
+    args: [
+      input.chunkId,
+      input.itemVersionId,
+      ...(input.audienceIds ?? []),
+      input.title,
+      input.summary ?? "",
+      input.body,
+      input.updatedAt ?? new Date().toISOString(),
+    ],
+  });
+  return true;
+}
+
+export async function queryPostgresFts(
+  db: DbExec,
+  input: {
+    query: string;
+    allowedChunkIds?: readonly string[];
+    allowedAudienceIds?: readonly string[];
+    limit?: number;
+    namespace?: string;
+  },
+): Promise<PostgresFtsHit[]> {
+  const namespace = input.namespace ?? DEFAULT_SEARCH_NAMESPACE;
+  const names = searchNamespaceIdentifiers(namespace);
+  if (
+    !isPostgres() ||
+    input.allowedChunkIds?.length === 0 ||
+    input.allowedAudienceIds?.length === 0
+  )
+    return [];
+  const keys = input.allowedChunkIds?.length
+    ? `chunk_id IN (${input.allowedChunkIds.map(() => "?").join(", ")}) AND`
+    : "";
+  const audiences = audienceClause(input.allowedAudienceIds);
+  const limit = Math.max(1, Math.min(200, Math.floor(input.limit ?? 40)));
+  try {
+    const result = await db.execute({
+      sql: `SELECT chunk_id, item_version_id, ts_rank_cd(document, websearch_to_tsquery('simple', ?)) AS score FROM ${names.ftsTable} WHERE ${keys} document @@ websearch_to_tsquery('simple', ?)${audiences.sql} ORDER BY score DESC, chunk_id ASC LIMIT ?`,
+      args: [
+        input.query,
+        ...(input.allowedChunkIds ?? []),
+        input.query,
+        ...audiences.args,
+        limit,
+      ],
+    });
+    return result.rows.map((row) => ({
+      chunkId: String(row.chunk_id),
+      itemVersionId: String(row.item_version_id),
+      score: Number(row.score),
+    }));
+  } catch (error) {
+    // A read can race the first write for a tenant-specific namespace. Writers
+    // provision it; an absent lane simply contributes no candidates.
+    if (isMissingPostgresRelation(error)) return [];
+    throw error;
+  }
+}
+
+function isMissingPostgresRelation(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  return (error as { code?: unknown }).code === "42P01";
+}
+
+export async function deletePostgresFtsDocuments(
+  db: DbExec,
+  chunkIds: readonly string[],
+  namespace = DEFAULT_SEARCH_NAMESPACE,
+): Promise<number> {
+  const names = searchNamespaceIdentifiers(namespace);
+  if (!isPostgres() || !chunkIds.length) return 0;
+  await ensurePostgresFts(db, namespace);
+  const result = await db.execute({
+    sql: `DELETE FROM ${names.ftsTable} WHERE chunk_id IN (${chunkIds.map(() => "?").join(", ")})`,
+    args: [...chunkIds],
+  });
+  return result.rowsAffected;
+}
+
+export function reciprocalRankFusion<T>(
+  lanes: Readonly<Record<string, readonly RankedCandidate<T>[]>>,
+  options: { rankConstant?: number; limit?: number } = {},
+): FusedCandidate<T>[] {
+  const rankConstant = Math.max(1, options.rankConstant ?? 60);
+  const fused = new Map<string, FusedCandidate<T>>();
+  for (const [lane, candidates] of Object.entries(lanes)) {
+    candidates.forEach((candidate, index) => {
+      const rank = index + 1;
+      const current = fused.get(candidate.key) ?? {
+        ...candidate,
+        score: 0,
+        laneRanks: {},
+        reasons: [],
+      };
+      current.score += 1 / (rankConstant + rank);
+      current.laneRanks[lane] = rank;
+      if (candidate.reason && !current.reasons.includes(candidate.reason))
+        current.reasons.push(candidate.reason);
+      fused.set(candidate.key, current);
+    });
+  }
+  return [...fused.values()]
+    .sort((a, b) => b.score - a.score || a.key.localeCompare(b.key))
+    .slice(0, Math.max(1, options.limit ?? 40));
+}