dna-sdk 0.1.0

package/dist/adapters/resolvers/http.js

@@ -0,0 +1,145 @@
+/**
+ * HttpResolver — ResolverPort for http:/https: URIs.
+ *
+ * 1:1 parity with Python dna.v3.adapters.resolvers.http.
+ *
+ * Fetches manifest documents from HTTP endpoints. Supports two modes:
+ *
+ * 1. **Index mode** (default): GET {uri}/index.json → list of {kind, name, path}.
+ *    Each item is fetched individually: GET {uri}/{path} → raw dict.
+ *
+ * 2. **Bundle mode** (fallback): GET {uri} → list of raw dicts directly.
+ */
+import { mkdirSync, writeFileSync, mkdtempSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { ResolveNotFoundError, ResolveNetworkError, ResolveError, } from "../../kernel/protocols.js";
+import { rejectLegacyShorthand } from "./local.js";
+export class HttpResolver {
+    cacheKey(uri) {
+        const safe = uri.replace(/[^a-zA-Z0-9_-]/g, "-").replace(/^-+|-+$/g, "");
+        return `http-${safe}`.slice(0, 120);
+    }
+    async resolve(uri, dep) {
+        const baseUrl = uri.replace(/\/$/, "");
+        const requested = this._collectRequested(dep);
+        // Try index mode first
+        try {
+            const index = this._fetchJson(`${baseUrl}/index.json`);
+            if (Array.isArray(index)) {
+                return this._resolveFromIndex(baseUrl, index, requested);
+            }
+        }
+        catch (e) {
+            if (e instanceof ResolveError) {
+                // Fall through to bundle mode
+            }
+            else {
+                throw e;
+            }
+        }
+        // Fallback: bundle mode
+        try {
+            const bundle = this._fetchJson(baseUrl);
+            if (Array.isArray(bundle)) {
+                return this._resolveFromBundle(bundle, requested);
+            }
+        }
+        catch (e) {
+            if (e instanceof ResolveError) {
+                throw new ResolveError(`HTTP resolve failed for ${uri}: ${e.message}`);
+            }
+            throw e;
+        }
+        throw new ResolveError(`HTTP endpoint returned unexpected format: ${uri}`);
+    }
+    _fetchJson(url) {
+        const result = Bun.spawnSync(["curl", "-sf", "-H", "Accept: application/json", url]);
+        if (result.exitCode !== 0) {
+            const stderr = result.stderr.toString();
+            // curl exit code 22 = HTTP 4xx/5xx, 6 = DNS failure, 28 = timeout
+            if (stderr.includes("404") || result.stdout.toString().includes("404")) {
+                throw new ResolveNotFoundError(`Not found: ${url}`);
+            }
+            if (result.exitCode === 6 || result.exitCode === 7 || result.exitCode === 28) {
+                throw new ResolveNetworkError(`Network error fetching: ${url}`);
+            }
+            throw new ResolveError(`curl failed (exit ${result.exitCode}): ${url}`);
+        }
+        const body = result.stdout.toString();
+        if (!body.trim()) {
+            throw new ResolveNotFoundError(`Empty response from: ${url}`);
+        }
+        try {
+            return JSON.parse(body);
+        }
+        catch (e) {
+            throw new ResolveError(`Invalid JSON from ${url}: ${e}`);
+        }
+    }
+    _resolveFromIndex(baseUrl, index, requested) {
+        const items = [];
+        for (const entry of index) {
+            const kind = entry.kind ?? "";
+            const name = entry.name ?? "";
+            const path = entry.path ?? "";
+            if (requested && !this._matchesRequest(kind, name, requested)) {
+                continue;
+            }
+            let raw;
+            try {
+                raw = this._fetchJson(`${baseUrl}/${path}`);
+            }
+            catch {
+                continue;
+            }
+            const tmp = mkdtempSync(join(tmpdir(), "dna-http-"));
+            const itemDir = join(tmp, name);
+            mkdirSync(itemDir, { recursive: true });
+            writeFileSync(join(itemDir, "manifest.yaml"), JSON.stringify(raw, null, 2));
+            items.push({ name, kind, sourcePath: itemDir });
+        }
+        return items;
+    }
+    _resolveFromBundle(bundle, requested) {
+        const items = [];
+        for (const raw of bundle) {
+            const kind = raw.kind ?? "";
+            const metadata = raw.metadata ?? {};
+            const name = metadata.name ?? "";
+            if (!name)
+                continue;
+            if (requested && !this._matchesRequest(kind, name, requested)) {
+                continue;
+            }
+            const tmp = mkdtempSync(join(tmpdir(), "dna-http-"));
+            const itemDir = join(tmp, name);
+            mkdirSync(itemDir, { recursive: true });
+            writeFileSync(join(itemDir, "manifest.yaml"), JSON.stringify(raw, null, 2));
+            items.push({ name, kind, sourcePath: itemDir });
+        }
+        return items;
+    }
+    _collectRequested(dep) {
+        // i-010 — same normalization contract as LocalResolver._collectRequested:
+        // the legacy pre-v3 shorthand throws ResolveError before any fetch.
+        rejectLegacyShorthand(dep);
+        const result = {};
+        const items = dep.items ?? [];
+        for (const item of items) {
+            const kind = item.kind ?? "";
+            if (kind) {
+                result[kind] = item.names ?? [];
+            }
+        }
+        return Object.keys(result).length > 0 ? result : null;
+    }
+    _matchesRequest(kind, name, requested) {
+        if (!(kind in requested))
+            return false;
+        const names = requested[kind];
+        if (!names || names.length === 0)
+            return true;
+        return names.includes(name);
+    }
+}

package/dist/adapters/resolvers/index.d.ts

@@ -0,0 +1,3 @@
+export { LocalResolver } from "./local.js";
+export { HttpResolver } from "./http.js";
+export { GitHubResolver } from "./github.js";

package/dist/adapters/resolvers/index.js

@@ -0,0 +1,3 @@
+export { LocalResolver } from "./local.js";
+export { HttpResolver } from "./http.js";
+export { GitHubResolver } from "./github.js";

package/dist/adapters/resolvers/local.d.ts

@@ -0,0 +1,24 @@
+/**
+ * LocalResolver — ResolverPort for local: URIs.
+ *
+ * 1:1 parity with Python dna.v3.adapters.resolvers.local.
+ */
+import type { ResolvedItem, ResolverPort } from "../../kernel/protocols.js";
+export declare const LEGACY_SHORTHAND_KEYS: readonly ["skills", "souls", "agents", "actors", "guardrails"];
+/**
+ * Throw ResolveError if the dep uses the dead pre-v3 category shorthand.
+ *
+ * Shared by the local, github and http resolvers so the legacy format
+ * fails loud (an entry in `mi.resolveErrors`) with a rewrite recipe
+ * instead of silently resolving at the wrong granularity.
+ */
+export declare function rejectLegacyShorthand(dep: Record<string, unknown>): void;
+export declare class LocalResolver implements ResolverPort {
+    readonly baseDir: string | null;
+    constructor(baseDir?: string);
+    cacheKey(uri: string): string;
+    resolve(uri: string, dep: Record<string, unknown>): Promise<ResolvedItem[]>;
+    private _collectRequested;
+    private _resolveAll;
+    private _resolveByCategory;
+}

package/dist/adapters/resolvers/local.js

@@ -0,0 +1,132 @@
+/**
+ * LocalResolver — ResolverPort for local: URIs.
+ *
+ * 1:1 parity with Python dna.v3.adapters.resolvers.local.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { ResolveError } from "../../kernel/protocols.js";
+// i-009 / i-010 — pre-v3 dependency shorthand: category-list keys at the dep
+// top level (`skills: [...]`). DEAD format — the Genome contract is
+// `items: [{kind, names}]` and no resolver ever read the shorthand, so it
+// silently fell through to _resolveAll with the wrong granularity
+// (bundle SUBDIRECTORIES instead of bundles). Rejected loudly instead.
+// Twin of LEGACY_SHORTHAND_KEYS / reject_legacy_shorthand in
+// dna/adapters/resolvers/local.py — same keys, same message.
+export const LEGACY_SHORTHAND_KEYS = [
+    "skills",
+    "souls",
+    "agents",
+    "actors",
+    "guardrails",
+];
+/**
+ * Throw ResolveError if the dep uses the dead pre-v3 category shorthand.
+ *
+ * Shared by the local, github and http resolvers so the legacy format
+ * fails loud (an entry in `mi.resolveErrors`) with a rewrite recipe
+ * instead of silently resolving at the wrong granularity.
+ */
+export function rejectLegacyShorthand(dep) {
+    const legacy = LEGACY_SHORTHAND_KEYS.filter((k) => Array.isArray(dep[k]));
+    if (legacy.length > 0) {
+        const source = typeof dep.source === "string" ? dep.source : "<unknown>";
+        const singular = legacy[0].replace(/s+$/, "");
+        const kind = singular.charAt(0).toUpperCase() + singular.slice(1);
+        throw new ResolveError(`Dependency '${source}' uses the legacy '${legacy[0]}:' shorthand, ` +
+            `which is no longer read. Rewrite it in the v3 items format:\n` +
+            `  items:\n` +
+            `  - kind: ${kind}\n` +
+            `    names: [...]`);
+    }
+}
+export class LocalResolver {
+    baseDir;
+    constructor(baseDir) {
+        this.baseDir = baseDir ? resolve(baseDir) : null;
+    }
+    cacheKey(uri) {
+        const path = uri.replace(/^local:/, "");
+        const safe = path.replace(/[^a-zA-Z0-9_-]/g, "-").replace(/^-+|-+$/g, "");
+        return `local-${safe}`;
+    }
+    async resolve(uri, dep) {
+        const pathStr = uri.replace(/^local:/, "");
+        let localPath = pathStr;
+        if (!localPath.startsWith("/") && this.baseDir) {
+            localPath = resolve(this.baseDir, pathStr);
+        }
+        if (!existsSync(localPath)) {
+            return [];
+        }
+        // Normalize dep format
+        const requested = this._collectRequested(dep);
+        if (requested) {
+            return this._resolveByCategory(localPath, requested);
+        }
+        return this._resolveAll(localPath);
+    }
+    _collectRequested(dep) {
+        // The legacy pre-v3 shorthand (`skills: [...]` at the dep top level)
+        // throws ResolveError (i-009/i-010) — see `rejectLegacyShorthand`.
+        rejectLegacyShorthand(dep);
+        const result = {};
+        const items = dep.items ?? [];
+        for (const item of items) {
+            const kind = item.kind ?? "";
+            if (kind) {
+                const category = kind.toLowerCase() + "s"; // Skill -> skills
+                result[category] = item.names ?? []; // [] = all
+            }
+        }
+        return Object.keys(result).length > 0 ? result : null;
+    }
+    _resolveAll(source) {
+        const items = [];
+        const entries = readdirSync(source).sort();
+        for (const entry of entries) {
+            const full = join(source, entry);
+            if (!statSync(full).isDirectory() || entry.startsWith("."))
+                continue;
+            // Recurse into category dirs (skills/, souls/, agents/)
+            const subEntries = readdirSync(full).sort();
+            for (const sub of subEntries) {
+                const itemDir = join(full, sub);
+                if (statSync(itemDir).isDirectory()) {
+                    items.push({ name: sub, kind: "", sourcePath: itemDir });
+                }
+            }
+        }
+        return items;
+    }
+    _resolveByCategory(source, requested) {
+        const items = [];
+        for (const [category, names] of Object.entries(requested)) {
+            const categoryDir = join(source, category);
+            if (!existsSync(categoryDir))
+                continue;
+            if (names.length > 0) {
+                // Import specific names
+                for (const name of names) {
+                    for (const candidate of [join(categoryDir, name), join(source, name)]) {
+                        if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+                            items.push({ name, kind: "", sourcePath: candidate });
+                            break;
+                        }
+                    }
+                }
+            }
+            else {
+                // Import all from category
+                const entries = readdirSync(categoryDir).sort();
+                for (const entry of entries) {
+                    const subdir = join(categoryDir, entry);
+                    if (statSync(subdir).isDirectory()) {
+                        items.push({ name: entry, kind: "", sourcePath: subdir });
+                    }
+                }
+            }
+        }
+        return items;
+    }
+}

package/dist/adapters/search/driver.d.ts

@@ -0,0 +1,45 @@
+/**
+ * SQLite driver shim for the sqlite-vec search provider — the ONE place that
+ * papers over the two runtimes DNA's TS SDK runs under, so the provider itself
+ * is runtime-agnostic:
+ *
+ *   - Bun (the test runner) → `bun:sqlite`. Bun auto-loads SQLite on the first
+ *     `Database` open and extension loading must be enabled BEFORE that, via
+ *     `Database.setCustomSQLite(libPath)`. We probe for a libsqlite3 that allows
+ *     extensions (env `DNA_SQLITE_LIB`, then common macOS/Linux paths) exactly
+ *     once, before opening anything. Bun's own bundled SQLite already allows it
+ *     on most Linux builds, so the probe is a best-effort fallback.
+ *   - Node ≥22.5 → `node:sqlite` (`DatabaseSync`, `{ allowExtension: true }`),
+ *     which bundles a SQLite compiled with extension loading — no external lib.
+ *
+ * Both expose the tiny synchronous surface the provider needs. sqlite-vec is
+ * loaded into every opened connection. If no runtime can load the extension,
+ * `openSearchDb` throws `SqliteVecUnavailableError` — the provider surfaces it
+ * and callers (CLI, conformance kit) degrade/skip with a clear reason rather
+ * than crash.
+ */
+/** The minimal synchronous SQLite surface the provider drives. */
+export interface SearchDb {
+    exec(sql: string): void;
+    run(sql: string, params?: unknown[]): {
+        lastInsertRowid: number;
+    };
+    get<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | undefined;
+    all<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+    close(): void;
+}
+/** Thrown when no available runtime can load the sqlite-vec extension. */
+export declare class SqliteVecUnavailableError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Open a SQLite connection with sqlite-vec loaded, using whichever runtime
+ * driver is available. Throws {@link SqliteVecUnavailableError} when neither
+ * can load the extension.
+ */
+export declare function openSearchDb(path: string): Promise<SearchDb>;
+/** Pack a float vector into sqlite-vec's float32 blob layout (parity with the
+ *  Python `_serialize_f32`). */
+export declare function serializeF32(vector: number[]): Uint8Array;

package/dist/adapters/search/driver.js

@@ -0,0 +1,138 @@
+/**
+ * SQLite driver shim for the sqlite-vec search provider — the ONE place that
+ * papers over the two runtimes DNA's TS SDK runs under, so the provider itself
+ * is runtime-agnostic:
+ *
+ *   - Bun (the test runner) → `bun:sqlite`. Bun auto-loads SQLite on the first
+ *     `Database` open and extension loading must be enabled BEFORE that, via
+ *     `Database.setCustomSQLite(libPath)`. We probe for a libsqlite3 that allows
+ *     extensions (env `DNA_SQLITE_LIB`, then common macOS/Linux paths) exactly
+ *     once, before opening anything. Bun's own bundled SQLite already allows it
+ *     on most Linux builds, so the probe is a best-effort fallback.
+ *   - Node ≥22.5 → `node:sqlite` (`DatabaseSync`, `{ allowExtension: true }`),
+ *     which bundles a SQLite compiled with extension loading — no external lib.
+ *
+ * Both expose the tiny synchronous surface the provider needs. sqlite-vec is
+ * loaded into every opened connection. If no runtime can load the extension,
+ * `openSearchDb` throws `SqliteVecUnavailableError` — the provider surfaces it
+ * and callers (CLI, conformance kit) degrade/skip with a clear reason rather
+ * than crash.
+ */
+/** Thrown when no available runtime can load the sqlite-vec extension. */
+export class SqliteVecUnavailableError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "SqliteVecUnavailableError";
+    }
+}
+const isBun = typeof globalThis.Bun !== "undefined";
+// Candidate libsqlite3 paths that permit extension loading. An explicit
+// `DNA_SQLITE_LIB` override wins on any platform. Otherwise we only probe on
+// macOS: Apple's system libsqlite3 (which Bun uses there) has extension loading
+// DISABLED, so we point Bun at Homebrew's build. On Linux, Bun's bundled SQLite
+// already allows loadExtension, so we add NO candidate and trust it — forcing a
+// distro lib could regress if that build omitted extension support.
+function libCandidates() {
+    const out = [];
+    const proc = globalThis.process;
+    if (proc?.env?.DNA_SQLITE_LIB)
+        out.push(proc.env.DNA_SQLITE_LIB);
+    if (proc?.platform === "darwin") {
+        out.push("/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib", "/usr/local/opt/sqlite/lib/libsqlite3.dylib");
+    }
+    return out;
+}
+let bunCustomSqliteChosen = false;
+async function chooseBunSqlite() {
+    if (bunCustomSqliteChosen)
+        return;
+    bunCustomSqliteChosen = true; // decide once, before the first open
+    const { Database } = (await import("bun:sqlite"));
+    // Only set a custom lib if one exists on disk; otherwise trust Bun's bundled
+    // SQLite (extension loading works on most Linux builds out of the box).
+    let fs;
+    try {
+        fs = (await import("node:fs"));
+    }
+    catch {
+        return;
+    }
+    for (const path of libCandidates()) {
+        if (fs.existsSync(path)) {
+            try {
+                Database.setCustomSQLite(path);
+            }
+            catch {
+                /* already loaded or unsupported — fall through to bundled */
+            }
+            return;
+        }
+    }
+}
+async function openBun(path) {
+    await chooseBunSqlite();
+    const { Database } = (await import("bun:sqlite"));
+    const sqliteVec = await import("sqlite-vec");
+    const db = new Database(path);
+    try {
+        sqliteVec.load(db);
+    }
+    catch (err) {
+        db.close();
+        throw new SqliteVecUnavailableError("bun:sqlite could not load the sqlite-vec extension — set DNA_SQLITE_LIB "
+            + "to a libsqlite3 that permits extension loading (e.g. Homebrew's "
+            + "/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib).", { cause: err });
+    }
+    return {
+        exec: (sql) => db.exec(sql),
+        run: (sql, params = []) => {
+            const info = db.query(sql).run(...params);
+            return { lastInsertRowid: Number(info.lastInsertRowid) };
+        },
+        get: (sql, params = []) => db.query(sql).get(...params),
+        all: (sql, params = []) => db.query(sql).all(...params),
+        close: () => db.close(),
+    };
+}
+async function openNode(path) {
+    let DatabaseSync;
+    try {
+        ({ DatabaseSync } = (await import("node:sqlite")));
+    }
+    catch (err) {
+        throw new SqliteVecUnavailableError("node:sqlite is unavailable (needs Node ≥22.5 with --experimental-sqlite "
+            + "or ≥23.5). Run under Bun, or upgrade Node.", { cause: err });
+    }
+    const sqliteVec = await import("sqlite-vec");
+    const db = new DatabaseSync(path, { allowExtension: true });
+    try {
+        db.loadExtension(sqliteVec.getLoadablePath());
+    }
+    catch (err) {
+        db.close();
+        throw new SqliteVecUnavailableError("node:sqlite could not load the sqlite-vec extension.", { cause: err });
+    }
+    return {
+        exec: (sql) => db.exec(sql),
+        run: (sql, params = []) => {
+            const info = db.prepare(sql).run(...params);
+            return { lastInsertRowid: Number(info.lastInsertRowid) };
+        },
+        get: (sql, params = []) => db.prepare(sql).get(...params),
+        all: (sql, params = []) => db.prepare(sql).all(...params),
+        close: () => db.close(),
+    };
+}
+/**
+ * Open a SQLite connection with sqlite-vec loaded, using whichever runtime
+ * driver is available. Throws {@link SqliteVecUnavailableError} when neither
+ * can load the extension.
+ */
+export async function openSearchDb(path) {
+    return isBun ? openBun(path) : openNode(path);
+}
+/** Pack a float vector into sqlite-vec's float32 blob layout (parity with the
+ *  Python `_serialize_f32`). */
+export function serializeF32(vector) {
+    return new Uint8Array(new Float32Array(vector).buffer);
+}

package/dist/adapters/search/migrations.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Forward-only numbered migrations for the sqlite-vec search store (TS twin of
+ * `dna/adapters/search/migrations.py`).
+ *
+ * The debt rsh-memory-similarity-evolution (f-embeddings-ddl-debt) calls out:
+ * the embeddings sidecar had no owning migration upstream. Here the store's
+ * schema is OWNED by a numbered, append-only, idempotent migration recorded in
+ * the store's own `schema_migrations` control table. The vec0 virtual table
+ * needs the embedding width baked in, so `buildMigrations(dims)` interpolates
+ * it — the migration still owns the DDL, it just parametrizes the vector width.
+ *
+ * The TS SDK has no shared migration runner (only the Postgres source has its
+ * own), so {@link runSearchMigrations} is the small local analog of the Python
+ * `run_migrations` contract: same forward-only/append-only/idempotent-boot
+ * semantics, over the synchronous {@link SearchDb} surface.
+ */
+import type { SearchDb } from "./driver.js";
+/** version → one executescript payload (SQLite dialect). Parity with the Py
+ *  `build_migrations(dims)`. */
+export declare function buildMigrations(dims: number): Record<number, string>;
+/**
+ * Apply every pending migration in ascending version order (forward-only,
+ * append-only, idempotent boot). Returns the versions applied by THIS call —
+ * `[]` when the store is already up to date (the idempotent re-boot case).
+ */
+export declare function runSearchMigrations(db: SearchDb, migrations: Record<number, string>): number[];

package/dist/adapters/search/migrations.js

@@ -0,0 +1,58 @@
+/** version → one executescript payload (SQLite dialect). Parity with the Py
+ *  `build_migrations(dims)`. */
+export function buildMigrations(dims) {
+    if (dims < 1)
+        throw new Error(`embedding dims must be positive, got ${dims}`);
+    return {
+        1: `
+CREATE TABLE IF NOT EXISTS search_docs (
+    rowid      INTEGER PRIMARY KEY AUTOINCREMENT,
+    scope      TEXT NOT NULL,
+    kind       TEXT NOT NULL,
+    name       TEXT NOT NULL,
+    tenant     TEXT NOT NULL DEFAULT '',
+    text_hash  TEXT NOT NULL,
+    title      TEXT,
+    snippet    TEXT,
+    text       TEXT NOT NULL,
+    UNIQUE (scope, kind, name, tenant)
+);
+CREATE INDEX IF NOT EXISTS search_docs_lookup
+    ON search_docs (scope, kind, tenant);
+CREATE VIRTUAL TABLE IF NOT EXISTS search_vec USING vec0(
+    doc_rowid INTEGER PRIMARY KEY,
+    embedding float[${dims}]
+);
+CREATE VIRTUAL TABLE IF NOT EXISTS search_fts USING fts5(text);
+CREATE TABLE IF NOT EXISTS search_meta (
+    key   TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+);
+`,
+    };
+}
+/**
+ * Apply every pending migration in ascending version order (forward-only,
+ * append-only, idempotent boot). Returns the versions applied by THIS call —
+ * `[]` when the store is already up to date (the idempotent re-boot case).
+ */
+export function runSearchMigrations(db, migrations) {
+    db.exec("CREATE TABLE IF NOT EXISTS schema_migrations "
+        + "(version INTEGER PRIMARY KEY, applied_at TEXT NOT NULL)");
+    const applied = new Set(db.all("SELECT version FROM schema_migrations").map((r) => r.version));
+    const appliedNow = [];
+    const versions = Object.keys(migrations)
+        .map(Number)
+        .sort((a, b) => a - b);
+    for (const version of versions) {
+        if (applied.has(version))
+            continue;
+        db.exec(migrations[version]);
+        db.run("INSERT INTO schema_migrations (version, applied_at) VALUES (?, ?)", [
+            version,
+            new Date().toISOString(),
+        ]);
+        appliedNow.push(version);
+    }
+    return appliedNow;
+}

package/dist/adapters/search/rrf.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Reciprocal Rank Fusion — the pure, deterministic hybrid-fusion core.
+ *
+ * TypeScript twin of `dna/adapters/search/rrf.py`. RRF (Cormack et al. 2009)
+ * fuses several independently-ranked lists using only each item's RANK within
+ * each list — never the raw scores, which are incomparable across a cosine
+ * dense list and a BM25 lexical list. Each item accrues `1 / (k + rank)` (rank
+ * 1-based) from every list it appears in; items are ordered by descending fused
+ * score, ties broken by id ascending — fully deterministic and bit-identical to
+ * the Python implementation.
+ */
+/** RRF smoothing constant (the paper's value; the de-facto default). */
+export declare const DEFAULT_RRF_K = 60;
+/**
+ * Fuse ranked id-lists into one ranking via Reciprocal Rank Fusion.
+ *
+ * @param rankedLists each inner array is item ids in rank order (best first).
+ *   An id may appear across lists; duplicates WITHIN one list count at their
+ *   first (best) rank only.
+ * @param k RRF smoothing constant (`DEFAULT_RRF_K`); must be > 0.
+ * @returns `[id, fusedScore]` pairs sorted by fused score desc, ties by id asc.
+ */
+export declare function reciprocalRankFusion(rankedLists: string[][], k?: number): Array<[string, number]>;

package/dist/adapters/search/rrf.js

@@ -0,0 +1,42 @@
+/**
+ * Reciprocal Rank Fusion — the pure, deterministic hybrid-fusion core.
+ *
+ * TypeScript twin of `dna/adapters/search/rrf.py`. RRF (Cormack et al. 2009)
+ * fuses several independently-ranked lists using only each item's RANK within
+ * each list — never the raw scores, which are incomparable across a cosine
+ * dense list and a BM25 lexical list. Each item accrues `1 / (k + rank)` (rank
+ * 1-based) from every list it appears in; items are ordered by descending fused
+ * score, ties broken by id ascending — fully deterministic and bit-identical to
+ * the Python implementation.
+ */
+/** RRF smoothing constant (the paper's value; the de-facto default). */
+export const DEFAULT_RRF_K = 60;
+/**
+ * Fuse ranked id-lists into one ranking via Reciprocal Rank Fusion.
+ *
+ * @param rankedLists each inner array is item ids in rank order (best first).
+ *   An id may appear across lists; duplicates WITHIN one list count at their
+ *   first (best) rank only.
+ * @param k RRF smoothing constant (`DEFAULT_RRF_K`); must be > 0.
+ * @returns `[id, fusedScore]` pairs sorted by fused score desc, ties by id asc.
+ */
+export function reciprocalRankFusion(rankedLists, k = DEFAULT_RRF_K) {
+    if (k <= 0)
+        throw new Error(`RRF k must be positive, got ${k}`);
+    const scores = new Map();
+    for (const ranked of rankedLists) {
+        const seen = new Set();
+        ranked.forEach((docId, i) => {
+            if (seen.has(docId))
+                return; // first (best) rank wins for a repeated id
+            seen.add(docId);
+            const rank = i + 1;
+            scores.set(docId, (scores.get(docId) ?? 0) + 1 / (k + rank));
+        });
+    }
+    return [...scores.entries()].sort((a, b) => {
+        if (b[1] !== a[1])
+            return b[1] - a[1]; // score desc
+        return a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0; // id asc
+    });
+}