@seanhogg/builderforce-memory 2026.6.20 → 2026.6.28

package/src/index.ts

@@ -40,6 +40,59 @@ export type {
     Tokenizer,
 } from './session/index.js';
 
+// ── Limbic system (trainable affective dynamics) ──────────────────────────────
+export { LimbicSession } from './limbic/LimbicSession.js';
+export type { LimbicSessionOptions, LimbicGpuMode } from './limbic/LimbicSession.js';
+// Re-export the limbic engine primitives so consumers can use the model/trainer
+// and the region schema directly from @seanhogg/builderforce-memory.
+export {
+    LimbicModel,
+    LimbicTrainer,
+    LIMBIC_DIM,
+    LIMBIC_DIM_NAMES,
+    LIMBIC_STATE_DIM,
+    LIMBIC_BOUNDS,
+    NEUTRAL_STATE,
+    REGION,
+    clampState,
+    neutralState,
+    stateToRecord,
+    recordToState,
+} from '@seanhogg/builderforce-memory-engine';
+export type {
+    LimbicModelConfig,
+    LimbicForward,
+    LimbicSample,
+    LimbicTrainOptions,
+    LimbicDimName,
+    Region,
+} from '@seanhogg/builderforce-memory-engine';
+
+// ── Mixture-of-Experts (shared-expert hybrid — the Evermind generator's sparsity) ──
+// Re-exported from the engine so consumers reach it from @seanhogg/builderforce-memory.
+export {
+    SharedExpertMoE,
+    LoadBalanceAccumulator,
+    DEFAULT_MOE_CONFIG,
+    DEFAULT_MOE_SEED,
+    MoETrainer,
+    EvermindModelPackage,
+} from '@seanhogg/builderforce-memory-engine';
+export type {
+    MoEConfig,
+    MoEParam,
+    RouteResult,
+    MoESample,
+    MoETrainOptions,
+    MoEEpochResult,
+    EvermindModelManifest,
+    EvermindModelCard,
+    PackageMeta,
+    ValidationResult,
+} from '@seanhogg/builderforce-memory-engine';
+export { EvermindLM, EvermindLMTrainer } from '@seanhogg/builderforce-memory-engine';
+export type { EvermindLMConfig, LMGenerateOptions, TextCodec } from '@seanhogg/builderforce-memory-engine';
+
 // ── Runtime ───────────────────────────────────────────────────────────────────
 export { SSMRuntime }    from './runtime/SSMRuntime.js';
 export type { SSMRuntimeOptions, GenerateOptions } from './runtime/SSMRuntime.js';
@@ -73,6 +126,29 @@ export type {
 // ── Similarity primitives ──────────────────────────────────────────────────────
 export { cosineSimilarity, jaccardSimilarity, tokenize } from './similarity/index.js';
 
+// ── Retrieval (chunking, BM25, rank fusion, hybrid RAG) ────────────────────────
+export {
+    chunkText,
+    bm25Search,
+    reciprocalRankFusion,
+    maximalMarginalRelevance,
+    hybridRetrieve,
+} from './retrieval/index.js';
+export type {
+    Chunk,
+    ChunkOptions,
+    Bm25Doc,
+    Bm25Hit,
+    Bm25Options,
+    RankedList,
+    FusedHit,
+    MmrCandidate,
+    RetrievalCandidate,
+    HybridQuery,
+    HybridRetrieveOptions,
+    HybridHit,
+} from './retrieval/index.js';
+
 // ── Router ────────────────────────────────────────────────────────────────────
 export { InferenceRouter } from './router/InferenceRouter.js';
 export type {
@@ -92,6 +168,20 @@ export type {
     FactType,
 } from './memory/MemoryStore.js';
 
+// ── Cognition (Evermind — Write-Through Cognition) ────────────────────────────
+export { EvermindCognition, workspacePresenceGatherer } from './cognition/index.js';
+export type {
+    EvermindCognitionOptions,
+    WorkspacePresenceRule,
+    Claim,
+    CognitionFactStore,
+    CommitResult,
+    EvidenceContext,
+    EvidenceGatherer,
+    EvidenceResult,
+    Verdict,
+} from './cognition/index.js';
+
 // ── Distillation ──────────────────────────────────────────────────────────────
 export { DistillationEngine } from './distillation/DistillationEngine.js';
 export type {

package/src/limbic/LimbicSession.ts

@@ -0,0 +1,253 @@
+/**
+ * LimbicSession.ts – high-level facade over the limbic affect model.
+ *
+ * Mirrors {@link MambaSession}: collapses GPU acquisition, model construction,
+ * checkpoint load, and the trainer into a single `LimbicSession.create()` call,
+ * with the same WebGPU-or-CPU-fallback contract. The agent runtime consumes
+ * this through `@seanhogg/builderforce-memory` to run the limbic system on a
+ * self-hosted node (GPU via @webgpu/node when present, CPU otherwise).
+ *
+ *   const limbic = await LimbicSession.create({ gpuAdapter, checkpointBuffer });
+ *   const { delta, reward } = await limbic.step(experienceEmbedding, state);
+ *   await limbic.train(samples, { epochs: 30 });
+ *   const bin = limbic.exportWeights({ fp16: true });
+ */
+
+import {
+  LimbicModel,
+  LimbicTrainer,
+  LIMBIC_AFFECT_WGSL,
+  createStorageBuffer,
+  createEmptyStorageBuffer,
+  createUniformBuffer,
+  createComputePipeline,
+  createBindGroup,
+  dispatchKernel,
+  readBuffer,
+  type LimbicModelConfig,
+  type LimbicForward,
+  type LimbicSample,
+  type LimbicTrainOptions,
+} from "@seanhogg/builderforce-memory-engine";
+
+import { saveToIndexedDB, loadFromIndexedDB } from "../session/persistence.js";
+
+export type LimbicGpuMode = "webgpu" | "cpu-fallback" | "cpu";
+
+export interface LimbicSessionOptions {
+  /** Pre-created GPUAdapter (e.g. from @webgpu/node). When set, navigator.gpu is not used. */
+  gpuAdapter?: GPUAdapter;
+  /** Attempt a software (CPU) WebGPU adapter when no GPU is available. Default false. */
+  allowCpuFallback?: boolean;
+  /** Pre-read checkpoint bytes (Node: read the .bin with fs and pass the ArrayBuffer). */
+  checkpointBuffer?: ArrayBuffer;
+  /** IndexedDB key for save()/load(). Default 'limbic-default'. */
+  name?: string;
+  /** Injected IDBFactory (e.g. fake-indexeddb in Node). */
+  idbFactory?: IDBFactory;
+  /** Model configuration overrides. */
+  modelConfig?: Partial<LimbicModelConfig>;
+  /** Deterministic init seed. */
+  seed?: number;
+}
+
+interface StepBuffers {
+  win: GPUBuffer;
+  ws: GPUBuffer;
+  aLogit: GPUBuffer;
+  woutState: GPUBuffer;
+  boutState: GPUBuffer;
+}
+
+export class LimbicSession {
+  readonly model: LimbicModel;
+  readonly trainer: LimbicTrainer;
+  readonly device: GPUDevice | null;
+  readonly gpuMode: LimbicGpuMode;
+  private readonly _name: string;
+  private readonly _idbFactory: IDBFactory | undefined;
+
+  // GPU step pipeline + buffers, allocated lazily on first GPU step.
+  private _pipeline: GPUComputePipeline | null = null;
+  private _dimsBuf: GPUBuffer | null = null;
+  private _paramBufs: StepBuffers | null = null;
+  private _paramsDirty = true;
+
+  private constructor(
+    model: LimbicModel,
+    trainer: LimbicTrainer,
+    device: GPUDevice | null,
+    gpuMode: LimbicGpuMode,
+    name: string,
+    idbFactory: IDBFactory | undefined,
+  ) {
+    this.model = model;
+    this.trainer = trainer;
+    this.device = device;
+    this.gpuMode = gpuMode;
+    this._name = name;
+    this._idbFactory = idbFactory;
+  }
+
+  static async create(options: LimbicSessionOptions = {}): Promise<LimbicSession> {
+    let device: GPUDevice | null = null;
+    let gpuMode: LimbicGpuMode = "cpu";
+
+    if (options.gpuAdapter != null) {
+      try {
+        device = await options.gpuAdapter.requestDevice();
+        gpuMode = "webgpu";
+      } catch {
+        device = null;
+        gpuMode = "cpu";
+      }
+    } else if (typeof navigator !== "undefined" && navigator.gpu) {
+      try {
+        const adapter = await navigator.gpu.requestAdapter({ powerPreference: "high-performance" });
+        if (adapter) {
+          device = await adapter.requestDevice();
+          gpuMode = "webgpu";
+        }
+      } catch {
+        device = null;
+      }
+      if (!device && options.allowCpuFallback && typeof navigator !== "undefined" && navigator.gpu) {
+        try {
+          const fb = await navigator.gpu.requestAdapter({ forceFallbackAdapter: true });
+          if (fb) {
+            device = await fb.requestDevice();
+            gpuMode = "cpu-fallback";
+          }
+        } catch {
+          device = null;
+        }
+      }
+    }
+
+    const model = new LimbicModel({ ...options.modelConfig, seed: options.seed });
+    if (options.checkpointBuffer) {
+      model.loadWeights(options.checkpointBuffer);
+    }
+    const trainer = new LimbicTrainer(model, device);
+    return new LimbicSession(model, trainer, device, gpuMode, options.name ?? "limbic-default", options.idbFactory);
+  }
+
+  /** One affect step. Uses the GPU kernel when a device is available, else CPU. */
+  async step(input: ArrayLike<number>, state: ArrayLike<number>, hidden?: ArrayLike<number>): Promise<LimbicForward> {
+    const h = hidden ?? this.model.initHidden();
+    if (!this.device) return this.model.forward(input, h, state);
+    return this._stepGpu(input, h, state);
+  }
+
+  private _ensureGpuStep(): { pipeline: GPUComputePipeline; params: StepBuffers; dims: GPUBuffer } {
+    const device = this.device!;
+    if (!this._pipeline) {
+      this._pipeline = createComputePipeline(device, LIMBIC_AFFECT_WGSL, "affect_step");
+      const { inputDim, hiddenDim, stateDim } = this.model.config;
+      const dims = new ArrayBuffer(16);
+      new Uint32Array(dims).set([inputDim, hiddenDim, stateDim, 0]);
+      this._dimsBuf = createUniformBuffer(device, dims);
+    }
+    if (this._paramsDirty || !this._paramBufs) {
+      this._destroyParamBufs();
+      this._paramBufs = {
+        win: createStorageBuffer(device, this.model.win, false),
+        ws: createStorageBuffer(device, this.model.ws, false),
+        aLogit: createStorageBuffer(device, this.model.aLogit, false),
+        woutState: createStorageBuffer(device, this.model.woutState, false),
+        boutState: createStorageBuffer(device, this.model.boutState, false),
+      };
+      this._paramsDirty = false;
+    }
+    return { pipeline: this._pipeline, params: this._paramBufs, dims: this._dimsBuf! };
+  }
+
+  private async _stepGpu(input: ArrayLike<number>, hPrev: ArrayLike<number>, sPrev: ArrayLike<number>): Promise<LimbicForward> {
+    const device = this.device!;
+    const { inputDim, hiddenDim, stateDim } = this.model.config;
+    const { pipeline, params, dims } = this._ensureGpuStep();
+
+    const xBuf = createStorageBuffer(device, Float32Array.from({ length: inputDim }, (_, i) => input[i] ?? 0), false);
+    const hBuf = createStorageBuffer(device, Float32Array.from({ length: hiddenDim }, (_, j) => hPrev[j] ?? 0), false);
+    const sBuf = createStorageBuffer(device, Float32Array.from({ length: stateDim }, (_, k) => sPrev[k] ?? 0), false);
+    const hOut = createEmptyStorageBuffer(device, hiddenDim * 4, true);
+    const dOut = createEmptyStorageBuffer(device, stateDim * 4, true);
+
+    const bg = createBindGroup(device, pipeline, [
+      dims,
+      params.win,
+      params.ws,
+      params.aLogit,
+      params.woutState,
+      params.boutState,
+      xBuf,
+      hBuf,
+      sBuf,
+      hOut,
+      dOut,
+    ]);
+    dispatchKernel(device, pipeline, bg, [1, 1, 1]);
+
+    const hidden = (await readBuffer(device, hOut, hiddenDim * 4)).subarray(0, hiddenDim);
+    const delta = (await readBuffer(device, dOut, stateDim * 4)).subarray(0, stateDim);
+
+    // Reward head is small — compute on CPU from the GPU-produced hidden state.
+    let reward = this.model.boutReward[0]!;
+    for (let j = 0; j < hiddenDim; j++) reward += this.model.woutReward[j]! * hidden[j]!;
+
+    xBuf.destroy();
+    hBuf.destroy();
+    sBuf.destroy();
+    hOut.destroy();
+    dOut.destroy();
+
+    return { hidden: Float32Array.from(hidden), delta: Float32Array.from(delta), reward };
+  }
+
+  /** Train the affect model on observed experiences. Marks GPU step buffers dirty. */
+  async train(samples: LimbicSample[], opts?: LimbicTrainOptions): Promise<number[]> {
+    const losses = await this.trainer.train(samples, opts);
+    this._paramsDirty = true; // weights changed → GPU step buffers must be re-uploaded
+    return losses;
+  }
+
+  evaluate(samples: LimbicSample[]): number {
+    return this.trainer.evaluate(samples);
+  }
+
+  exportWeights(opts?: { fp16?: boolean }): ArrayBuffer {
+    return this.model.exportWeights(opts);
+  }
+
+  /** Persist weights to IndexedDB under the session name. */
+  async save(): Promise<void> {
+    await saveToIndexedDB(`limbic_${this._name}`, this.model.exportWeights({ fp16: true }), this._idbFactory);
+  }
+
+  /** Load weights from IndexedDB; returns true if a checkpoint was found. */
+  async load(): Promise<boolean> {
+    const buf = await loadFromIndexedDB(`limbic_${this._name}`, this._idbFactory);
+    if (!buf) return false;
+    this.model.loadWeights(buf);
+    this._paramsDirty = true;
+    return true;
+  }
+
+  private _destroyParamBufs(): void {
+    if (this._paramBufs) {
+      this._paramBufs.win.destroy();
+      this._paramBufs.ws.destroy();
+      this._paramBufs.aLogit.destroy();
+      this._paramBufs.woutState.destroy();
+      this._paramBufs.boutState.destroy();
+      this._paramBufs = null;
+    }
+  }
+
+  destroy(): void {
+    this._destroyParamBufs();
+    this._dimsBuf?.destroy();
+    this._dimsBuf = null;
+    this._pipeline = null;
+  }
+}

package/src/memory/MemoryStore.ts

@@ -10,6 +10,7 @@
 
 import { SSMError } from '../errors/SSMError.js';
 import { tokenize, jaccardSimilarity, cosineSimilarity } from '../similarity/index.js';
+import { hybridRetrieve, type RetrievalCandidate, type HybridRetrieveOptions } from '../retrieval/index.js';
 
 export type FactType = 'text' | 'json' | 'number' | 'boolean';
 
@@ -265,6 +266,41 @@ export class MemoryStore {
         return scored.slice(0, topK).map(s => s.entry);
     }
 
+    /**
+     * Hybrid recall: fuses dense (SSM-embedding cosine) and sparse (BM25 lexical)
+     * rankings via Reciprocal Rank Fusion, then applies an MMR diversity rerank.
+     *
+     * This is the production RAG retrieval path — it catches both semantic matches
+     * (embeddings) and exact-token matches (BM25 — identifiers, codes, rare names)
+     * that cosine-only `recallSimilar` misses, and avoids returning near-duplicate
+     * facts. Degrades to BM25-only when no embedding-capable runtime is available,
+     * so it is always strictly at least as good as the lexical fallback.
+     */
+    async recallHybrid(
+        query: string,
+        topK: number,
+        runtime?: SSMRuntimeRef,
+        opts?: HybridRetrieveOptions,
+    ): Promise<MemoryEntry[]> {
+        const all = await this.recallAll();
+        if (all.length === 0) return [];
+
+        // Embed candidates + query where a runtime is available; null vectors are
+        // fine — hybridRetrieve degrades that candidate to BM25-only.
+        const canEmbed = runtime != null && typeof runtime.embed === 'function';
+        const queryVec = canEmbed ? (await this._embedWithCache(runtime, query)) ?? undefined : undefined;
+
+        const candidates: RetrievalCandidate[] = [];
+        for (const entry of all) {
+            const vector = canEmbed ? (await this._embedWithCache(runtime, entry.content)) ?? undefined : undefined;
+            candidates.push({ id: entry.key, text: entry.content, vector });
+        }
+
+        const hits = hybridRetrieve({ text: query, vector: queryVec }, candidates, { topK, ...opts });
+        const byKey = new Map(all.map(e => [e.key, e]));
+        return hits.map(h => byKey.get(h.id)).filter((e): e is MemoryEntry => !!e);
+    }
+
     /**
      * Returns a cached embedding for `text`, computing it via `runtime.embed()`
      * on a cache miss. Returns `null` (never throws) when embedding is

package/src/retrieval/HybridRetriever.ts

@@ -0,0 +1,122 @@
+/**
+ * HybridRetriever — dense + sparse retrieval with rank fusion and diversity rerank.
+ *
+ * This is the piece that takes the memory layer from "cosine-only similarity" to a
+ * full hybrid RAG retriever:
+ *
+ *   1. Dense:  cosine over embeddings (SSM hidden-state vectors, or any embedder).
+ *   2. Sparse: BM25 lexical scoring (catches exact tokens dense search misses).
+ *   3. Fuse:   Reciprocal Rank Fusion combines the two rankings.
+ *   4. Rerank: optional MMR pass for relevance/novelty trade-off (diversity).
+ *
+ * It is storage-agnostic — give it candidates (id + text + optional vector) and a
+ * query (text + optional vector). It degrades gracefully: no query vector / no
+ * candidate vectors → BM25-only; no overlap → dense-only.
+ */
+
+import { cosineSimilarity } from '../similarity/index.js';
+import { bm25Search, type Bm25Options } from './bm25.js';
+import { reciprocalRankFusion, maximalMarginalRelevance, type MmrCandidate } from './fusion.js';
+
+export interface RetrievalCandidate {
+    id: string;
+    text: string;
+    /** Precomputed embedding. Omit to exclude this candidate from the dense pass. */
+    vector?: Float32Array;
+}
+
+export interface HybridQuery {
+    text: string;
+    /** Query embedding. Omit for BM25-only retrieval. */
+    vector?: Float32Array;
+}
+
+export interface HybridRetrieveOptions {
+    /** Number of results to return. Default 5. */
+    topK?: number;
+    /** RRF damping constant. Default 60. */
+    rrfK?: number;
+    /** Relative weight of the dense ranking in fusion. Default 1. */
+    denseWeight?: number;
+    /** Relative weight of the sparse (BM25) ranking in fusion. Default 1. */
+    sparseWeight?: number;
+    /** Apply MMR diversity rerank over the fused top results. Default true. */
+    rerank?: boolean;
+    /** MMR relevance/diversity trade-off (1 = pure relevance). Default 0.7. */
+    mmrLambda?: number;
+    /** BM25 tuning. */
+    bm25?: Bm25Options;
+}
+
+export interface HybridHit {
+    id: string;
+    text: string;
+    /** Fused RRF score (pre-rerank). */
+    score: number;
+}
+
+/**
+ * Runs the full hybrid pipeline over `candidates` and returns the top-K hits.
+ * Pure given its inputs (embeddings are supplied by the caller) so it is directly
+ * unit-testable without a model or vector DB.
+ */
+export function hybridRetrieve(
+    query: HybridQuery,
+    candidates: RetrievalCandidate[],
+    opts: HybridRetrieveOptions = {},
+): HybridHit[] {
+    const topK = opts.topK ?? 5;
+    if (candidates.length === 0) return [];
+
+    const byId = new Map(candidates.map(c => [c.id, c]));
+
+    // ── Dense ranking (cosine) ────────────────────────────────────────────────
+    let denseIds: string[] = [];
+    if (query.vector) {
+        denseIds = candidates
+            .filter(c => c.vector && c.vector.length > 0)
+            .map(c => ({ id: c.id, score: cosineSimilarity(query.vector!, c.vector!) }))
+            .sort((a, b) => b.score - a.score)
+            .map(h => h.id);
+    }
+
+    // ── Sparse ranking (BM25) ─────────────────────────────────────────────────
+    const sparseIds = bm25Search(query.text, candidates, opts.bm25).map(h => h.id);
+
+    // ── Fuse ──────────────────────────────────────────────────────────────────
+    const fused = reciprocalRankFusion(
+        [
+            { ids: denseIds, weight: opts.denseWeight ?? 1 },
+            { ids: sparseIds, weight: opts.sparseWeight ?? 1 },
+        ].filter(l => l.ids.length > 0),
+        opts.rrfK ?? 60,
+    );
+    if (fused.length === 0) return [];
+
+    // ── Rerank (MMR over fused top, using whatever vectors we have) ────────────
+    const rerank = opts.rerank ?? true;
+    let orderedIds: string[];
+    if (rerank && query.vector) {
+        // Consider a generous fused window so MMR has room to diversify.
+        const window = fused.slice(0, Math.max(topK * 4, topK));
+        const mmrCands: MmrCandidate[] = window
+            .map(f => byId.get(f.id))
+            .filter((c): c is RetrievalCandidate => !!c && !!c.vector && c.vector.length > 0)
+            .map(c => ({ id: c.id, vector: c.vector! }));
+        if (mmrCands.length > 0) {
+            const reranked = maximalMarginalRelevance(query.vector, mmrCands, topK, opts.mmrLambda ?? 0.7);
+            // MMR only ranks the vectored subset; append any remaining fused ids after.
+            const seen = new Set(reranked);
+            orderedIds = [...reranked, ...fused.map(f => f.id).filter(id => !seen.has(id))];
+        } else {
+            orderedIds = fused.map(f => f.id);
+        }
+    } else {
+        orderedIds = fused.map(f => f.id);
+    }
+
+    const fusedScore = new Map(fused.map(f => [f.id, f.score]));
+    return orderedIds
+        .slice(0, topK)
+        .map(id => ({ id, text: byId.get(id)!.text, score: fusedScore.get(id)! }));
+}

package/src/retrieval/bm25.ts

@@ -0,0 +1,83 @@
+/**
+ * BM25 (Okapi) lexical ranking.
+ *
+ * The keyword half of hybrid retrieval. Dense vector search matches meaning but
+ * misses exact tokens (identifiers, error codes, rare names); BM25 catches those.
+ * Fusing the two (see {@link ./fusion}) is what lifts the memory layer from
+ * "cosine only" to a hybrid retriever on par with Weaviate-style search.
+ *
+ * Pure and zero-dependency — reuses the shared `tokenize` from ../similarity.
+ */
+
+import { tokenize } from '../similarity/index.js';
+
+export interface Bm25Options {
+    /** Term-frequency saturation. Higher = TF matters more. Default 1.5. */
+    k1?: number;
+    /** Length normalisation, 0..1. Higher = penalise long docs more. Default 0.75. */
+    b?: number;
+}
+
+export interface Bm25Doc {
+    id: string;
+    text: string;
+}
+
+export interface Bm25Hit {
+    id: string;
+    score: number;
+}
+
+/**
+ * Scores every document against `query` with Okapi BM25, returning hits sorted by
+ * descending score (documents with no query-term overlap score 0 and are dropped).
+ * Builds the index inline — for a recall over a bounded candidate set (the memory
+ * store / a vector pre-filter) this is O(N·terms) and needs no persistence.
+ */
+export function bm25Search(query: string, docs: Bm25Doc[], opts: Bm25Options = {}): Bm25Hit[] {
+    const k1 = opts.k1 ?? 1.5;
+    const b = opts.b ?? 0.75;
+    const N = docs.length;
+    if (N === 0) return [];
+
+    const queryTerms = new Set(tokenize(query));
+    if (queryTerms.size === 0) return [];
+
+    // Per-doc term frequencies + document lengths.
+    const docTerms: { id: string; tf: Map<string, number>; len: number }[] = [];
+    const df = new Map<string, number>();
+    let totalLen = 0;
+
+    for (const doc of docs) {
+        const tokens = tokenize(doc.text);
+        const tf = new Map<string, number>();
+        for (const t of tokens) tf.set(t, (tf.get(t) ?? 0) + 1);
+        for (const t of tf.keys()) if (queryTerms.has(t)) df.set(t, (df.get(t) ?? 0) + 1);
+        docTerms.push({ id: doc.id, tf, len: tokens.length });
+        totalLen += tokens.length;
+    }
+    const avgdl = totalLen / N || 1;
+
+    // idf with the +1 smoothing variant (always non-negative).
+    const idf = new Map<string, number>();
+    for (const term of queryTerms) {
+        const n = df.get(term) ?? 0;
+        idf.set(term, Math.log(1 + (N - n + 0.5) / (n + 0.5)));
+    }
+
+    const hits: Bm25Hit[] = [];
+    for (const d of docTerms) {
+        let score = 0;
+        for (const term of queryTerms) {
+            const f = d.tf.get(term);
+            if (!f) continue;
+            const numer = f * (k1 + 1);
+            const denom = f + k1 * (1 - b + b * (d.len / avgdl));
+            score += idf.get(term)! * (numer / denom);
+        }
+        if (score > 0) hits.push({ id: d.id, score });
+    }
+
+    hits.sort((a, b) => b.score - a.score);
+    return hits;
+}