@seanhogg/builderforce-memory 2026.7.12 → 2026.9.27

package/dist/ingest/parsers.js

@@ -0,0 +1,306 @@
+/**
+ * ingest/parsers.ts — format handlers, as a registry.
+ *
+ * Each parser turns a source into sections and recovers whatever STRUCTURE the
+ * format carries, because structure that survives parsing becomes filterable
+ * metadata, and metadata is what makes retrieval precise:
+ *
+ *   • Markdown keeps its heading path, so a chunk knows it lives under
+ *     "Security › Data retention" and a citation can say so.
+ *   • Rows keep every typed column, so `status = 'open'` is a database predicate
+ *     rather than something the embedding has to imply.
+ *   • JSON keeps its pointer, so a value can be traced back to its exact location.
+ *
+ * A parser that returned only text would throw all of that away and force the
+ * retriever to recover it statistically — the single most common reason a RAG
+ * pilot answers plausibly and cites nothing verifiable.
+ */
+const textOf = (source) => source.content.kind === 'text' ? source.content.text : '';
+const mediaTypeOf = (source) => source.content.kind === 'text' ? (source.content.mediaType ?? 'text/plain').toLowerCase() : '';
+// ── structured rows ───────────────────────────────────────────────────────────
+/**
+ * Serialises a row as `field: value` lines.
+ *
+ * Field names are kept in the text on purpose: an embedding of `"status: open"`
+ * sits near a question about open items, whereas a bare `"open"` sits near
+ * nothing useful. The typed values are ALSO emitted as metadata, so the same fact
+ * is both semantically searchable and exactly filterable.
+ */
+export function serializeRow(row) {
+    return Object.entries(row)
+        .filter(([, v]) => v !== null && v !== undefined && v !== '')
+        .map(([k, v]) => `${k}: ${Array.isArray(v) ? v.join(', ') : String(v)}`)
+        .join('\n');
+}
+export const rowsParser = {
+    id: 'rows',
+    accepts: (source) => source.content.kind === 'rows',
+    parse: (source) => {
+        if (source.content.kind !== 'rows')
+            return [];
+        const { rows, rowIdField } = source.content;
+        return rows.map((row, index) => {
+            const metadata = { ...row };
+            metadata['rowIndex'] = index;
+            if (rowIdField && row[rowIdField] !== undefined) {
+                metadata['rowId'] = String(row[rowIdField]);
+            }
+            return { text: serializeRow(row), metadata };
+        });
+    },
+};
+// ── CSV ───────────────────────────────────────────────────────────────────────
+/**
+ * RFC 4180 subset: quoted fields, doubled quotes, embedded newlines and commas.
+ * Enough for the exports enterprises actually hand over, without a dependency.
+ */
+export function parseCsv(text, delimiter = ',') {
+    const rows = [];
+    let field = '';
+    let record = [];
+    let quoted = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (quoted) {
+            if (ch === '"') {
+                if (text[i + 1] === '"') {
+                    field += '"';
+                    i++;
+                }
+                else
+                    quoted = false;
+            }
+            else
+                field += ch;
+            continue;
+        }
+        if (ch === '"') {
+            quoted = true;
+            continue;
+        }
+        if (ch === delimiter) {
+            record.push(field);
+            field = '';
+            continue;
+        }
+        if (ch === '\n' || ch === '\r') {
+            if (ch === '\r' && text[i + 1] === '\n')
+                i++;
+            record.push(field);
+            rows.push(record);
+            record = [];
+            field = '';
+            continue;
+        }
+        field += ch;
+    }
+    if (field !== '' || record.length > 0) {
+        record.push(field);
+        rows.push(record);
+    }
+    const header = rows.shift();
+    if (!header)
+        return [];
+    return rows
+        .filter((r) => r.some((cell) => cell.trim() !== ''))
+        .map((cells) => {
+        const row = {};
+        header.forEach((name, i) => {
+            row[name.trim()] = coerce(cells[i] ?? '');
+        });
+        return row;
+    });
+}
+/**
+ * Numbers and booleans are recovered from CSV text so range filters work.
+ * A value that merely *looks* numeric but has a leading zero (an account number,
+ * a zip code) stays a string — coercing it would silently destroy the identifier.
+ */
+function coerce(raw) {
+    const value = raw.trim();
+    if (value === '')
+        return '';
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    if (/^-?(0|[1-9]\d*)(\.\d+)?$/.test(value)) {
+        const n = Number(value);
+        if (Number.isFinite(n))
+            return n;
+    }
+    return value;
+}
+export const csvParser = {
+    id: 'csv',
+    accepts: (source) => {
+        const type = mediaTypeOf(source);
+        return type.includes('csv') || type.includes('tab-separated');
+    },
+    parse: (source) => {
+        const delimiter = mediaTypeOf(source).includes('tab-separated') ? '\t' : ',';
+        const rows = parseCsv(textOf(source), delimiter);
+        return rowsParser.parse({ ...source, content: { kind: 'rows', rows } });
+    },
+};
+// ── JSON ──────────────────────────────────────────────────────────────────────
+/**
+ * An array of objects is treated as rows (the common export shape); anything else
+ * is flattened to leaf paths so a value keeps its JSON pointer.
+ */
+export const jsonParser = {
+    id: 'json',
+    accepts: (source) => mediaTypeOf(source).includes('json'),
+    parse: (source) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(textOf(source));
+        }
+        catch {
+            // Malformed JSON is still text worth indexing; degrading beats dropping
+            // the document, and the parser name on the chunk records what happened.
+            return plainTextParser.parse(source);
+        }
+        if (Array.isArray(parsed) && parsed.every((v) => v && typeof v === 'object' && !Array.isArray(v))) {
+            return rowsParser.parse({
+                ...source,
+                content: { kind: 'rows', rows: parsed },
+            });
+        }
+        const leaves = flatten(parsed, '');
+        if (leaves.length === 0)
+            return [];
+        return [{
+                text: leaves.map(([path, value]) => `${path}: ${value}`).join('\n'),
+                metadata: { leafCount: leaves.length },
+            }];
+    },
+};
+function flatten(value, path, out = []) {
+    if (value === null || typeof value !== 'object') {
+        out.push([path || '/', String(value)]);
+        return out;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((v, i) => flatten(v, `${path}/${i}`, out));
+        return out;
+    }
+    for (const [key, v] of Object.entries(value)) {
+        flatten(v, `${path}/${key}`, out);
+    }
+    return out;
+}
+// ── Markdown ──────────────────────────────────────────────────────────────────
+export const markdownParser = {
+    id: 'markdown',
+    accepts: (source) => {
+        const type = mediaTypeOf(source);
+        return type.includes('markdown') || type.includes('/md');
+    },
+    parse: (source) => {
+        const lines = textOf(source).split('\n');
+        const sections = [];
+        // Heading level -> text, so a chunk carries its full breadcrumb rather than
+        // only its nearest heading.
+        const path = [];
+        let buffer = [];
+        const flush = () => {
+            const text = buffer.join('\n').trim();
+            buffer = [];
+            if (!text)
+                return;
+            const metadata = {};
+            if (path.length) {
+                metadata['headingPath'] = path.join(' › ');
+                metadata['heading'] = path[path.length - 1];
+                metadata['headingDepth'] = path.length;
+            }
+            sections.push({ text, metadata });
+        };
+        let inFence = false;
+        for (const line of lines) {
+            if (/^\s*```/.test(line))
+                inFence = !inFence;
+            const heading = inFence ? null : /^(#{1,6})\s+(.*)$/.exec(line);
+            if (heading) {
+                flush();
+                const depth = heading[1].length;
+                path.length = Math.min(path.length, depth - 1);
+                path[depth - 1] = heading[2].trim();
+                path.length = depth;
+                continue;
+            }
+            buffer.push(line);
+        }
+        flush();
+        return sections;
+    },
+};
+// ── HTML ──────────────────────────────────────────────────────────────────────
+export const htmlParser = {
+    id: 'html',
+    accepts: (source) => mediaTypeOf(source).includes('html') || mediaTypeOf(source).includes('xml'),
+    parse: (source) => {
+        const raw = textOf(source);
+        const titleMatch = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(raw);
+        const text = raw
+            // script/style content is code, not prose — indexing it poisons recall.
+            .replace(/<(script|style)[^>]*>[\s\S]*?<\/\1>/gi, ' ')
+            .replace(/<!--[\s\S]*?-->/g, ' ')
+            .replace(/<\/(p|div|section|article|li|tr|h[1-6])>/gi, '\n')
+            .replace(/<br\s*\/?>/gi, '\n')
+            .replace(/<[^>]+>/g, ' ')
+            .replace(/&nbsp;/g, ' ')
+            .replace(/&amp;/g, '&')
+            .replace(/&lt;/g, '<')
+            .replace(/&gt;/g, '>')
+            .replace(/&quot;/g, '"')
+            .replace(/&#39;/g, "'")
+            .replace(/[ \t]+/g, ' ')
+            .replace(/\n{3,}/g, '\n\n')
+            .trim();
+        if (!text)
+            return [];
+        const metadata = {};
+        if (titleMatch?.[1])
+            metadata['htmlTitle'] = titleMatch[1].trim();
+        return [{ text, metadata }];
+    },
+};
+// ── plain text ────────────────────────────────────────────────────────────────
+export const plainTextParser = {
+    id: 'text',
+    accepts: (source) => source.content.kind === 'text',
+    parse: (source) => {
+        const text = textOf(source).trim();
+        return text ? [{ text }] : [];
+    },
+};
+// ── registry ──────────────────────────────────────────────────────────────────
+/** Order matters: the first parser that accepts a source handles it. */
+export const BUILTIN_PARSERS = [
+    rowsParser,
+    csvParser,
+    jsonParser,
+    markdownParser,
+    htmlParser,
+    plainTextParser,
+];
+export class ParserRegistry {
+    _parsers;
+    constructor(parsers = BUILTIN_PARSERS) {
+        this._parsers = [...parsers];
+    }
+    /** Registers a parser at the FRONT, so it can override a builtin. */
+    register(parser) {
+        this._parsers.unshift(parser);
+        return this;
+    }
+    resolve(source) {
+        return this._parsers.find((p) => p.accepts(source));
+    }
+    list() {
+        return this._parsers.map((p) => p.id);
+    }
+}
+//# sourceMappingURL=parsers.js.map

package/dist/ingest/parsers.js.map

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

package/dist/ingest/types.d.ts

@@ -0,0 +1,114 @@
+/**
+ * ingest/types.ts — the ingestion vocabulary.
+ *
+ * The pipeline handles STRUCTURED and UNSTRUCTURED sources through one path, which
+ * is the point. A support ticket export (rows, typed columns, foreign keys) and a
+ * policy PDF's text both end up as chunks with typed metadata; the difference is
+ * which parser ran, not which pipeline. That is what makes a query like
+ * "summarise open P1 tickets about billing" answerable — `priority` and `status`
+ * survive as *filterable metadata* instead of being flattened into prose the
+ * embedding has to recover.
+ */
+import type { MetadataRecord, MetadataValue } from '../vectorstore/types.js';
+/** One row of a structured source (a DB result set, a CSV, a spreadsheet). */
+export type StructuredRow = Record<string, MetadataValue>;
+export type SourceContent = {
+    kind: 'text';
+    text: string;
+    mediaType?: string;
+} | {
+    kind: 'rows';
+    rows: StructuredRow[];
+    rowIdField?: string;
+};
+export interface SourceDocument {
+    /** Stable id in the ORIGIN system. Re-ingesting the same id replaces its chunks. */
+    id: string;
+    content: SourceContent;
+    /** Owning tenant. Written to every chunk and enforced on every read. */
+    tenantId: string;
+    /**
+     * Principal ids permitted to retrieve this document. Defaults to `['*']`
+     * (tenant-public). Written to every chunk so ACL evaluation happens inside the
+     * database query, not after the fact.
+     */
+    acl?: string[];
+    /** Classification level; readers declare a ceiling via `AccessScope`. */
+    sensitivity?: number;
+    /** Arbitrary filterable metadata copied onto every chunk. */
+    metadata?: MetadataRecord;
+    /** Human-facing title, used in citations. */
+    title?: string;
+    /** Origin URI, used in citations. */
+    uri?: string;
+}
+/** A parser's output: a span of text plus whatever structure it recovered. */
+export interface ParsedSection {
+    text: string;
+    /** Section-scoped metadata — heading path, row id, JSON pointer, … */
+    metadata?: MetadataRecord;
+}
+/**
+ * Parsers are registry entries, so a new format (PDF text layer, DOCX, a bespoke
+ * log) is registered rather than branched into the pipeline.
+ */
+export interface DocumentParser {
+    readonly id: string;
+    /** True when this parser handles the source. First match in registry order wins. */
+    accepts(source: SourceDocument): boolean;
+    parse(source: SourceDocument): ParsedSection[];
+}
+/** Identity of one stored chunk, for incremental sync. */
+export interface ChunkFingerprint {
+    id: string;
+    /** Content hash — an unchanged hash means the chunk need not be re-embedded. */
+    hash: string;
+}
+/**
+ * Records which chunks each source produced last time.
+ *
+ * Supplying one enables `diff` sync: only changed chunks are re-embedded (the
+ * expensive step) and only vanished chunks are deleted. Without it the pipeline
+ * falls back to `replace`, which is correct but re-embeds everything.
+ */
+export interface IngestManifest {
+    get(sourceId: string): Promise<ChunkFingerprint[] | undefined>;
+    set(sourceId: string, fingerprints: ChunkFingerprint[]): Promise<void>;
+    delete(sourceId: string): Promise<void>;
+}
+/** Batch embedder. Batched because per-text calls are the classic N+1 of RAG. */
+export type BatchEmbedder = (texts: string[]) => Promise<Float32Array[]>;
+export type SyncStrategy = 
+/** Re-embed only changed chunks, delete only vanished ones. Needs a manifest. */
+'diff'
+/** Delete the source's existing chunks, then write the new set. */
+ | 'replace'
+/** Write without deleting anything — for append-only corpora. */
+ | 'append';
+export interface IngestionReport {
+    documents: number;
+    sections: number;
+    chunks: number;
+    /** Chunks sent to the embedder — the cost driver. */
+    embedded: number;
+    upserted: number;
+    /** Chunks whose hash was unchanged and were skipped entirely. */
+    skippedUnchanged: number;
+    /** Chunks deleted because they no longer exist in the source. */
+    deletedStale: number;
+    failures: Array<{
+        sourceId: string;
+        error: string;
+    }>;
+    durationMs: number;
+    /** Trace id covering the whole run, when a tracer is attached. */
+    traceId?: string;
+}
+/** Metadata keys the pipeline reserves on every chunk it writes. */
+export declare const SOURCE_ID_FIELD = "sourceId";
+export declare const CHUNK_INDEX_FIELD = "chunkIndex";
+export declare const CONTENT_HASH_FIELD = "contentHash";
+export declare const TITLE_FIELD = "title";
+export declare const URI_FIELD = "uri";
+export declare const PARSER_FIELD = "parser";
+//# sourceMappingURL=types.d.ts.map

package/dist/ingest/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/ingest/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7E,8EAA8E;AAC9E,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAE1D,MAAM,MAAM,aAAa,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,aAAa,EAAE,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE,MAAM,WAAW,cAAc;IAC3B,oFAAoF;IACpF,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,aAAa,CAAC;IACvB,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,GAAG,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,OAAO,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC;IACzC,KAAK,CAAC,MAAM,EAAE,cAAc,GAAG,aAAa,EAAE,CAAC;CAClD;AAED,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC3B,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,GAAG,SAAS,CAAC,CAAC;IAC/D,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAED,iFAAiF;AACjF,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;AAEzE,MAAM,MAAM,YAAY;AACpB,iFAAiF;AAC/E,MAAM;AACR,mEAAmE;GACjE,SAAS;AACX,iEAAiE;GAC/D,QAAQ,CAAC;AAEf,MAAM,WAAW,eAAe;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,gBAAgB,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,oEAAoE;AACpE,eAAO,MAAM,eAAe,aAAa,CAAC;AAC1C,eAAO,MAAM,iBAAiB,eAAe,CAAC;AAC9C,eAAO,MAAM,kBAAkB,gBAAgB,CAAC;AAChD,eAAO,MAAM,WAAW,UAAU,CAAC;AACnC,eAAO,MAAM,SAAS,QAAQ,CAAC;AAC/B,eAAO,MAAM,YAAY,WAAW,CAAC"}

package/dist/ingest/types.js

@@ -0,0 +1,19 @@
+/**
+ * ingest/types.ts — the ingestion vocabulary.
+ *
+ * The pipeline handles STRUCTURED and UNSTRUCTURED sources through one path, which
+ * is the point. A support ticket export (rows, typed columns, foreign keys) and a
+ * policy PDF's text both end up as chunks with typed metadata; the difference is
+ * which parser ran, not which pipeline. That is what makes a query like
+ * "summarise open P1 tickets about billing" answerable — `priority` and `status`
+ * survive as *filterable metadata* instead of being flattened into prose the
+ * embedding has to recover.
+ */
+/** Metadata keys the pipeline reserves on every chunk it writes. */
+export const SOURCE_ID_FIELD = 'sourceId';
+export const CHUNK_INDEX_FIELD = 'chunkIndex';
+export const CONTENT_HASH_FIELD = 'contentHash';
+export const TITLE_FIELD = 'title';
+export const URI_FIELD = 'uri';
+export const PARSER_FIELD = 'parser';
+//# sourceMappingURL=types.js.map

package/dist/ingest/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/ingest/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAmGH,oEAAoE;AACpE,MAAM,CAAC,MAAM,eAAe,GAAG,UAAU,CAAC;AAC1C,MAAM,CAAC,MAAM,iBAAiB,GAAG,YAAY,CAAC;AAC9C,MAAM,CAAC,MAAM,kBAAkB,GAAG,aAAa,CAAC;AAChD,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC;AACnC,MAAM,CAAC,MAAM,SAAS,GAAG,KAAK,CAAC;AAC/B,MAAM,CAAC,MAAM,YAAY,GAAG,QAAQ,CAAC"}

package/dist/memory/MemoryStore.d.ts

@@ -30,6 +30,23 @@ export interface MemoryEntry {
     /** Importance weight in the range 0–1. Default: 0.5. */
     importance?: number;
 }
+/**
+ * Which ranker produced a recall ordering. Matches the vocabulary the gateway's
+ * Evermind recall/validate surfaces already report, so a host can render one chip
+ * ("Semantic recall" / "Lexical recall (fallback)") regardless of which layer
+ * answered.
+ */
+export type RecallMethod = 'embedding' | 'lexical';
+/** A recalled entry with its relevance score (higher = closer). */
+export interface ScoredMemory {
+    entry: MemoryEntry;
+    score: number;
+}
+/** A ranked recall: the hits plus the ranker that ordered them. */
+export interface RankedRecall {
+    hits: ScoredMemory[];
+    method: RecallMethod;
+}
 export interface RememberOptions {
     /** Override the store-level defaultTtlMs for this entry. */
     ttlMs?: number;
@@ -171,6 +188,22 @@ export declare class MemoryStore {
      * so it is always strictly at least as good as the lexical fallback.
      */
     recallHybrid(query: string, topK: number, runtime?: SSMRuntimeRef, opts?: HybridRetrieveOptions): Promise<MemoryEntry[]>;
+    /**
+     * The hybrid retrieval path with its evidence attached: each hit's fused score,
+     * plus WHICH ranker produced the ordering.
+     *
+     * {@link recallHybrid} is the convenience wrapper that throws both away, so
+     * there is exactly one implementation of the blend — and it is the shared
+     * `hybridRetrieve` → `reciprocalRankFusion` primitive, never a second hand-
+     * rolled mix of cosine and word overlap.
+     *
+     * `method` is honest rather than aspirational: `'embedding'` means the query
+     * really did embed and the dense ranking really did participate in the fusion;
+     * `'lexical'` means no model was available (or embedding failed) and the
+     * ordering is BM25 alone. Callers surface it so a user can tell semantic
+     * recall from the fallback instead of guessing.
+     */
+    recallRanked(query: string, topK: number, runtime?: SSMRuntimeRef, opts?: HybridRetrieveOptions): Promise<RankedRecall>;
     /**
      * Returns a cached embedding for `text`, computing it via `runtime.embed()`
      * on a cache miss. Returns `null` (never throws) when embedding is

package/dist/memory/MemoryStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MemoryStore.d.ts","sourceRoot":"","sources":["../../src/memory/MemoryStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAmE,KAAK,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAEpI,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D,MAAM,WAAW,WAAW;IACxB,GAAG,EAAU,MAAM,CAAC;IACpB,OAAO,EAAM,MAAM,CAAC;IACpB,SAAS,EAAI,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,GAAG,CAAC,EAAS,MAAM,CAAC;IACpB,6CAA6C;IAC7C,KAAK,CAAC,EAAO,MAAM,CAAC;IACpB,0DAA0D;IAC1D,IAAI,CAAC,EAAQ,QAAQ,CAAC;IACtB,uCAAuC;IACvC,IAAI,CAAC,EAAQ,MAAM,EAAE,CAAC;IACtB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC5B,4DAA4D;IAC5D,KAAK,CAAC,EAAO,MAAM,CAAC;IACpB,IAAI,CAAC,EAAQ,QAAQ,CAAC;IACtB,IAAI,CAAC,EAAQ,MAAM,EAAE,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IAC/B,iDAAiD;IACjD,MAAM,CAAC,EAAS,MAAM,CAAC;IACvB,+FAA+F;IAC/F,UAAU,CAAC,EAAK,MAAM,CAAC;IACvB;;;;;OAKG;IACH,UAAU,CAAC,EAAK,UAAU,CAAC;IAC3B;;;OAGG;IACH,YAAY,CAAC,EAAG,MAAM,CAAC;IACvB;;;;OAIG;IACH,YAAY,CAAC,EAAG,MAAM,CAAC;IACvB;;;;OAIG;IACH,UAAU,CAAC,EAAK,MAAM,CAAC;IACvB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CAC1B;AAcD,UAAU,eAAe;IACrB,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,WAAW,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAClD;AAID,KAAK,aAAa,GAAG,GAAG,CAAC;AAKzB,qBAAa,WAAW;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAU;IACtC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiC;IACtD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsB;IAClD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsB;IAClD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,GAAG,CAA4B;IACvC,OAAO,CAAC,WAAW,CAA+C;IAClE,sEAAsE;IACtE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmC;IAC/D,gFAAgF;IAChF,OAAO,CAAC,aAAa,CAAiB;IAOtC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmC;IACjE,OAAO,CAAC,WAAW,CAA0B;IAC7C,kEAAkE;IAClE,OAAO,CAAC,SAAS,CAAM;IACvB,sEAAsE;IACtE,OAAO,CAAC,aAAa,CAAiB;gBAE1B,IAAI,GAAE,kBAAuB;IAYzC,OAAO,CAAC,KAAK;IAwCb,OAAO,CAAC,UAAU;IAOlB,mCAAmC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBnF;;;;OAIG;YACW,WAAW;IA0BzB;;;;OAIG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAYzC,2EAA2E;IAC3E,cAAc,IAAI,IAAI;IAOtB;;;OAGG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAW3D,0DAA0D;IACpD,SAAS,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAgBzC;;;OAGG;IACG,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAKrD;;OAEG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAKtD;;;;;;;;;;;OAWG;IACG,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAIjG;;;;;OAKG;IACG,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAqCtI;;;;;;;;;OASG;IACG,YAAY,CACd,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,aAAa,EACvB,IAAI,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,WAAW,EAAE,CAAC;IAoBzB;;;;OAIG;YACW,eAAe;IAiC7B;;;;;;;;OAQG;YACW,UAAU;IAqDxB;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAkBrC,0DAA0D;IACpD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOxC,wDAAwD;IAClD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAc5B;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAIzC;;;;;;OAMG;IACG,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,QAAQ,EAAE,OAAO,GAAG,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAavF,mFAAmF;YACrE,OAAO;IAQrB;;;;OAIG;IACG,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1D;;;OAGG;IACG,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC;CAGhE"}
+{"version":3,"file":"MemoryStore.d.ts","sourceRoot":"","sources":["../../src/memory/MemoryStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAmE,KAAK,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAEpI,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D,MAAM,WAAW,WAAW;IACxB,GAAG,EAAU,MAAM,CAAC;IACpB,OAAO,EAAM,MAAM,CAAC;IACpB,SAAS,EAAI,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,GAAG,CAAC,EAAS,MAAM,CAAC;IACpB,6CAA6C;IAC7C,KAAK,CAAC,EAAO,MAAM,CAAC;IACpB,0DAA0D;IAC1D,IAAI,CAAC,EAAQ,QAAQ,CAAC;IACtB,uCAAuC;IACvC,IAAI,CAAC,EAAQ,MAAM,EAAE,CAAC;IACtB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,SAAS,CAAC;AAEnD,mEAAmE;AACnE,MAAM,WAAW,YAAY;IACzB,KAAK,EAAE,WAAW,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,mEAAmE;AACnE,MAAM,WAAW,YAAY;IACzB,IAAI,EAAE,YAAY,EAAE,CAAC;IACrB,MAAM,EAAE,YAAY,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC5B,4DAA4D;IAC5D,KAAK,CAAC,EAAO,MAAM,CAAC;IACpB,IAAI,CAAC,EAAQ,QAAQ,CAAC;IACtB,IAAI,CAAC,EAAQ,MAAM,EAAE,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IAC/B,iDAAiD;IACjD,MAAM,CAAC,EAAS,MAAM,CAAC;IACvB,+FAA+F;IAC/F,UAAU,CAAC,EAAK,MAAM,CAAC;IACvB;;;;;OAKG;IACH,UAAU,CAAC,EAAK,UAAU,CAAC;IAC3B;;;OAGG;IACH,YAAY,CAAC,EAAG,MAAM,CAAC;IACvB;;;;OAIG;IACH,YAAY,CAAC,EAAG,MAAM,CAAC;IACvB;;;;OAIG;IACH,UAAU,CAAC,EAAK,MAAM,CAAC;IACvB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CAC1B;AAcD,UAAU,eAAe;IACrB,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,WAAW,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAClD;AAID,KAAK,aAAa,GAAG,GAAG,CAAC;AAKzB,qBAAa,WAAW;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAU;IACtC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiC;IACtD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsB;IAClD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsB;IAClD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,GAAG,CAA4B;IACvC,OAAO,CAAC,WAAW,CAA+C;IAClE,sEAAsE;IACtE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmC;IAC/D,gFAAgF;IAChF,OAAO,CAAC,aAAa,CAAiB;IAOtC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmC;IACjE,OAAO,CAAC,WAAW,CAA0B;IAC7C,kEAAkE;IAClE,OAAO,CAAC,SAAS,CAAM;IACvB,sEAAsE;IACtE,OAAO,CAAC,aAAa,CAAiB;gBAE1B,IAAI,GAAE,kBAAuB;IAYzC,OAAO,CAAC,KAAK;IAwCb,OAAO,CAAC,UAAU;IAOlB,mCAAmC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBnF;;;;OAIG;YACW,WAAW;IA0BzB;;;;OAIG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAYzC,2EAA2E;IAC3E,cAAc,IAAI,IAAI;IAOtB;;;OAGG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAW3D,0DAA0D;IACpD,SAAS,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAgBzC;;;OAGG;IACG,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAKrD;;OAEG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAKtD;;;;;;;;;;;OAWG;IACG,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAIjG;;;;;OAKG;IACG,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAqCtI;;;;;;;;;OASG;IACG,YAAY,CACd,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,aAAa,EACvB,IAAI,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,WAAW,EAAE,CAAC;IAIzB;;;;;;;;;;;;;;OAcG;IACG,YAAY,CACd,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,aAAa,EACvB,IAAI,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,YAAY,CAAC;IA4BxB;;;;OAIG;YACW,eAAe;IAiC7B;;;;;;;;OAQG;YACW,UAAU;IAqDxB;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAkBrC,0DAA0D;IACpD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOxC,wDAAwD;IAClD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAc5B;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAIzC;;;;;;OAMG;IACG,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,QAAQ,EAAE,OAAO,GAAG,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAavF,mFAAmF;YACrE,OAAO;IAQrB;;;;OAIG;IACG,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1D;;;OAGG;IACG,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC;CAGhE"}

package/dist/memory/MemoryStore.js

@@ -261,21 +261,47 @@ export class MemoryStore {
      * so it is always strictly at least as good as the lexical fallback.
      */
     async recallHybrid(query, topK, runtime, opts) {
+        return (await this.recallRanked(query, topK, runtime, opts)).hits.map(h => h.entry);
+    }
+    /**
+     * The hybrid retrieval path with its evidence attached: each hit's fused score,
+     * plus WHICH ranker produced the ordering.
+     *
+     * {@link recallHybrid} is the convenience wrapper that throws both away, so
+     * there is exactly one implementation of the blend — and it is the shared
+     * `hybridRetrieve` → `reciprocalRankFusion` primitive, never a second hand-
+     * rolled mix of cosine and word overlap.
+     *
+     * `method` is honest rather than aspirational: `'embedding'` means the query
+     * really did embed and the dense ranking really did participate in the fusion;
+     * `'lexical'` means no model was available (or embedding failed) and the
+     * ordering is BM25 alone. Callers surface it so a user can tell semantic
+     * recall from the fallback instead of guessing.
+     */
+    async recallRanked(query, topK, runtime, opts) {
         const all = await this.recallAll();
         if (all.length === 0)
-            return [];
+            return { hits: [], method: 'lexical' };
         // 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 = [];
         for (const entry of all) {
-            const vector = canEmbed ? (await this._embedWithCache(runtime, entry.content)) ?? undefined : undefined;
+            const vector = queryVec ? (await this._embedWithCache(runtime, entry.content)) ?? undefined : undefined;
             candidates.push({ id: entry.key, text: entry.content, vector });
         }
+        // The dense ranking only exists when the query embedded AND at least one
+        // candidate did — anything less is a lexical ordering wearing a label.
+        const dense = !!queryVec && candidates.some(c => !!c.vector);
         const hits = hybridRetrieve({ text: query, vector: queryVec }, candidates, { topK, annThreshold: this._annThreshold, ...opts });
         const byKey = new Map(all.map(e => [e.key, e]));
-        return hits.map(h => byKey.get(h.id)).filter((e) => !!e);
+        return {
+            hits: hits
+                .map(h => { const entry = byKey.get(h.id); return entry ? { entry, score: h.score } : null; })
+                .filter((h) => !!h),
+            method: dense ? 'embedding' : 'lexical',
+        };
     }
     /**
      * Returns a cached embedding for `text`, computing it via `runtime.embed()`