@aid-framework/runtime 0.0.0 → 0.1.48

package/dist/retrieval/metrics.js

@@ -0,0 +1,200 @@
+/**
+ * Metrics over a retrieved set.
+ *
+ * The shipped `Metric` scores `(case, prediction: string)`. That signature cannot
+ * express these metrics: recall@k and MRR score a *ranked set of passages with
+ * provenance*, and a citation-grounding score has to look at where each passage came
+ * from. Encoding a retrieved set into one string would make every metric re-parse it,
+ * and the parse would become the thing under test.
+ *
+ * So the retrieval metrics get their own protocol here rather than widening the
+ * shipped one. Widening `Metric` would change the meaning of an interface the eval
+ * gate already threshold-checks, and would do so for every existing implementation.
+ * The new protocol is additive and reuses {@link MetricResult}.
+ *
+ * The two protocols share the part the gate actually consumes -- `name` and
+ * `deterministic` -- which is what lets retrieval metrics be handed to the shipped
+ * gate's `metrics` option. See `retrieval/gate.ts` for why that hand-off needs a cast
+ * and why the cast is sound.
+ *
+ * `deterministic` is `true` for all three, and that is a claim the gate enforces:
+ * none of these metrics calls a model, and every tie is broken by chunk id, so the
+ * same retrieved set always scores the same.
+ */
+import { ConfigurationError } from '../errors.js';
+import { MetricResult } from '../evals/metrics.js';
+import { repr } from '../internal/json.js';
+/**
+ * One retrieval question and the documents that should answer it.
+ *
+ * This mirrors the IR's `retrieval` metric node field for field, and it exists
+ * because `EvalCase` carries `metadata: Record<string, string>` -- a string map,
+ * which cannot hold `expectDocs` without inventing an encoding. The expected
+ * documents, and `k`, are what a retrieval metric needs, so they are typed here
+ * instead of smuggled through a string.
+ */
+export class RetrievalCase {
+    id;
+    query;
+    expectDocs;
+    k;
+    constructor(init) {
+        if (init.id.length === 0)
+            throw new ConfigurationError('case id must not be empty');
+        if (init.expectDocs.length === 0) {
+            throw new ConfigurationError('a retrieval case needs at least one expected document');
+        }
+        if (!Number.isInteger(init.k) || init.k <= 0) {
+            throw new ConfigurationError('a retrieval case needs a positive k');
+        }
+        this.id = init.id;
+        this.query = init.query;
+        this.expectDocs = [...init.expectDocs];
+        this.k = init.k;
+    }
+    /** Build a case from the IR's `{kind, expectDocs, k}` node. */
+    static fromSpec(init) {
+        return new RetrievalCase({
+            id: init.caseId,
+            query: init.query,
+            expectDocs: init.spec.expectDocs,
+            k: init.spec.k,
+        });
+    }
+}
+/**
+ * Fraction of expected documents present in the top `k`.
+ *
+ * Duplicated passages do not inflate the score: {@link RetrievalResult.docIds} is
+ * de-duplicated, so a document that contributed three passages counts once. Recall is
+ * about which documents were found.
+ */
+export class RecallAtK {
+    _name;
+    _minScore;
+    constructor(options = {}) {
+        this._name = options.name ?? 'recall@k';
+        this._minScore = options.minScore ?? 1.0;
+    }
+    get name() {
+        return this._name;
+    }
+    get deterministic() {
+        return true;
+    }
+    async score(entry, retrieved) {
+        const expected = new Set(entry.expectDocs);
+        const foundInTop = new Set(retrieved.docIds.slice(0, entry.k));
+        const found = new Set([...expected].filter((docId) => foundInTop.has(docId)));
+        const score = found.size / expected.size;
+        const missing = [...expected]
+            .filter((docId) => !found.has(docId))
+            .sort((left, right) => (left < right ? -1 : 1));
+        return new MetricResult({
+            metric: this.name,
+            score,
+            passed: score >= this._minScore,
+            detail: missing.length === 0 ? '' : `missing: ${missing.join(', ')}`,
+        });
+    }
+}
+/**
+ * Reciprocal rank of the first expected document, averaged over cases.
+ *
+ * Scored per case, so the "mean" is taken by the gate across cases and runs. One
+ * number per case keeps the metric a drop-in for the gate's per-case arithmetic.
+ */
+export class MeanReciprocalRank {
+    _name;
+    _minScore;
+    constructor(options = {}) {
+        this._name = options.name ?? 'mrr';
+        this._minScore = options.minScore ?? 0.5;
+    }
+    get name() {
+        return this._name;
+    }
+    get deterministic() {
+        return true;
+    }
+    async score(entry, retrieved) {
+        const expected = new Set(entry.expectDocs);
+        const ranked = retrieved.docIds.slice(0, entry.k);
+        for (const [offset, docId] of ranked.entries()) {
+            if (expected.has(docId)) {
+                const rank = offset + 1;
+                const score = 1.0 / rank;
+                return new MetricResult({
+                    metric: this.name,
+                    score,
+                    passed: score >= this._minScore,
+                    detail: `first expected document ${repr(docId)} at rank ${rank}`,
+                });
+            }
+        }
+        const sortedExpected = [...expected].sort((left, right) => (left < right ? -1 : 1));
+        return new MetricResult({
+            metric: this.name,
+            score: 0.0,
+            passed: this._minScore <= 0.0,
+            detail: `none of ${sortedExpected.join(', ')} were retrieved within k=${entry.k}`,
+        });
+    }
+}
+/**
+ * Fraction of expected documents that a returned item cites *correctly*.
+ *
+ * Distinct from recall because it scores citations rather than document ids, and
+ * because it checks integrity first: a citation whose `chunkId` or `docId` disagrees
+ * with the passage it is attached to is worse than a missing citation, since it sends
+ * a reader to the wrong place while looking authoritative. Any such mismatch scores 0
+ * regardless of what was retrieved.
+ *
+ * This definition is authored here: the IR has no citation metric kind, so there is
+ * no upstream semantics to match. It is stated rather than derived.
+ */
+export class CitationGrounding {
+    _name;
+    _minScore;
+    constructor(options = {}) {
+        this._name = options.name ?? 'citation-grounding';
+        this._minScore = options.minScore ?? 1.0;
+    }
+    get name() {
+        return this._name;
+    }
+    get deterministic() {
+        return true;
+    }
+    async score(entry, retrieved) {
+        const broken = retrieved.items.filter((item) => item.citation.chunkId !== item.chunk.chunkId || item.citation.docId !== item.chunk.docId);
+        const first = broken[0];
+        if (first !== undefined) {
+            return new MetricResult({
+                metric: this.name,
+                score: 0.0,
+                passed: false,
+                detail: `${broken.length} citation(s) disagree with the passage they name, ` +
+                    `first: ${first.citation.toString()} vs chunk ${first.chunk.chunkId}`,
+            });
+        }
+        const expected = new Set(entry.expectDocs);
+        const cited = new Set(retrieved.items.map((item) => item.citation.docId));
+        const grounded = new Set([...expected].filter((docId) => cited.has(docId)));
+        const score = grounded.size / expected.size;
+        const missing = [...expected]
+            .filter((docId) => !grounded.has(docId))
+            .sort((left, right) => (left < right ? -1 : 1));
+        return new MetricResult({
+            metric: this.name,
+            score,
+            passed: score >= this._minScore,
+            detail: missing.length === 0 ? '' : `uncited: ${missing.join(', ')}`,
+        });
+    }
+}
+/** The retrieval metrics this runtime ships, in a stable order. */
+export function retrievalMetrics() {
+    return [new RecallAtK(), new MeanReciprocalRank(), new CitationGrounding()];
+}
+//# sourceMappingURL=metrics.js.map

package/dist/retrieval/metrics.js.map

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

package/dist/retrieval/pgvector.d.ts

@@ -0,0 +1,62 @@
+/**
+ * A pgvector-backed store, provisioned locally and never touched by CI.
+ *
+ * The driver is optional, so this module must be importable without it. Nothing at
+ * module scope imports it; the load happens inside {@link loadDriver} on first use,
+ * and a missing driver becomes a {@link ConfigurationError} that names the package to
+ * install. Importing the retrieval package therefore cannot fail because a database
+ * dependency is absent, which is what lets the default dependency set stay unchanged
+ * and what keeps every required gate on the in-memory store.
+ *
+ * Two consequences of that choice are deliberate and visible:
+ *
+ * - The driver arrives as an untyped value, so `unknown` reaches this file. It is
+ *   confined to this one adapter rather than spreading a suppressed import across the
+ *   retrieval package.
+ * - Every statement is a fixed string with positional placeholders. The embedding
+ *   column is declared dimension-less rather than `vector(1536)`, so no computed
+ *   identifier is ever interpolated into SQL, and the pinned width is enforced where
+ *   the pin actually lives: the caller's `PinnedEmbedding`.
+ *
+ * Correctness here is expected to match the in-memory adapter, but nothing checks
+ * that: this adapter is not gate-covered, and its SQL path runs only on a machine
+ * where someone brought the database up themselves.
+ */
+import { SearchHit, StoreRecord } from './stores.js';
+import type { StoreKind } from './types.js';
+/**
+ * Resolve an `env:NAME` reference to the variable's value.
+ *
+ * An `env:` reference names a variable, not an alias: nothing here reaches the model
+ * catalog, so resolving it at run time cannot silently change which store a run wrote
+ * to.
+ */
+export declare function resolveUri(uri: string | null | undefined): string;
+/** pgvector's text input format, so its own package is not a dependency. */
+export declare function vectorLiteral(vector: readonly number[]): string;
+/** Accept either a driver-returned sequence or pgvector's text form. */
+export declare function parseVector(value: unknown): readonly number[];
+/** A single-table store: one row per chunk, keyed by content hash. */
+export declare class PgVectorStore {
+    private readonly _uri;
+    private readonly _dimensions;
+    private _connection;
+    private _closed;
+    constructor(options: {
+        readonly uri: string | null;
+        readonly dimensions?: number | null;
+    });
+    get kind(): StoreKind;
+    upsert(records: readonly StoreRecord[]): Promise<number>;
+    search(vector: readonly number[], options: {
+        readonly topK: number;
+        readonly metric: 'cosine' | 'dot' | 'l2';
+    }): Promise<readonly SearchHit[]>;
+    corpus(): Promise<readonly StoreRecord[]>;
+    close(): Promise<void>;
+    private connect;
+    private ensureSchema;
+    private params;
+    private record;
+}
+//# sourceMappingURL=pgvector.d.ts.map

package/dist/retrieval/pgvector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pgvector.d.ts","sourceRoot":"","sources":["../../src/retrieval/pgvector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAuF5C;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAkBjE;AAiBD,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAE/D;AAED,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAU7D;AAWD,sEAAsE;AACtE,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgB;IAC5C,OAAO,CAAC,WAAW,CAAyB;IAC5C,OAAO,CAAC,OAAO,CAAS;IAExB,YAAY,OAAO,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,EAGxF;IAED,IAAI,IAAI,IAAI,SAAS,CAEpB;IAEK,MAAM,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB7D;IAEK,MAAM,CACV,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,OAAO,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,KAAK,GAAG,IAAI,CAAA;KAAE,GAC3E,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAW/B;IAEK,MAAM,IAAI,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAI9C;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAO3B;YAEa,OAAO;YAgBP,YAAY;IAK1B,OAAO,CAAC,MAAM;IAed,OAAO,CAAC,MAAM;CAef"}

package/dist/retrieval/pgvector.js

@@ -0,0 +1,262 @@
+/**
+ * A pgvector-backed store, provisioned locally and never touched by CI.
+ *
+ * The driver is optional, so this module must be importable without it. Nothing at
+ * module scope imports it; the load happens inside {@link loadDriver} on first use,
+ * and a missing driver becomes a {@link ConfigurationError} that names the package to
+ * install. Importing the retrieval package therefore cannot fail because a database
+ * dependency is absent, which is what lets the default dependency set stay unchanged
+ * and what keeps every required gate on the in-memory store.
+ *
+ * Two consequences of that choice are deliberate and visible:
+ *
+ * - The driver arrives as an untyped value, so `unknown` reaches this file. It is
+ *   confined to this one adapter rather than spreading a suppressed import across the
+ *   retrieval package.
+ * - Every statement is a fixed string with positional placeholders. The embedding
+ *   column is declared dimension-less rather than `vector(1536)`, so no computed
+ *   identifier is ever interpolated into SQL, and the pinned width is enforced where
+ *   the pin actually lives: the caller's `PinnedEmbedding`.
+ *
+ * Correctness here is expected to match the in-memory adapter, but nothing checks
+ * that: this adapter is not gate-covered, and its SQL path runs only on a machine
+ * where someone brought the database up themselves.
+ */
+import { createRequire } from 'node:module';
+import { ConfigurationError, ProviderError } from '../errors.js';
+import { dumpsSorted, repr } from '../internal/json.js';
+import { SearchHit, StoreRecord } from './stores.js';
+import { Chunk } from './types.js';
+const ENV_PREFIX = 'env:';
+const DRIVER = 'pg';
+const CREATE_EXTENSION = 'CREATE EXTENSION IF NOT EXISTS vector';
+const CREATE_TABLE = `
+CREATE TABLE IF NOT EXISTS aid_chunks (
+    chunk_id text PRIMARY KEY,
+    doc_id text NOT NULL,
+    uri text NOT NULL,
+    chunk_index integer NOT NULL,
+    start_offset integer NOT NULL,
+    end_offset integer NOT NULL,
+    body text NOT NULL,
+    metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
+    embedding vector NOT NULL
+)
+`;
+const UPSERT = `
+INSERT INTO aid_chunks (
+    chunk_id, doc_id, uri, chunk_index, start_offset, end_offset, body, metadata, embedding
+) VALUES (
+    $1, $2, $3, $4, $5, $6, $7, $8::jsonb, $9::vector
+)
+ON CONFLICT (chunk_id) DO UPDATE SET
+    doc_id = EXCLUDED.doc_id,
+    uri = EXCLUDED.uri,
+    chunk_index = EXCLUDED.chunk_index,
+    start_offset = EXCLUDED.start_offset,
+    end_offset = EXCLUDED.end_offset,
+    body = EXCLUDED.body,
+    metadata = EXCLUDED.metadata,
+    embedding = EXCLUDED.embedding
+`;
+const COLUMNS = 'chunk_id, doc_id, uri, chunk_index, start_offset, end_offset, body, metadata, embedding';
+const CORPUS = `SELECT ${COLUMNS} FROM aid_chunks ORDER BY chunk_id`;
+// `<=>` is cosine distance, `<#>` is negative inner product and `<->` is L2 distance.
+// Each is rewritten into "higher is better" so callers see one orientation, matching
+// `stores.similarity`. The tie-break on `chunk_id` matches the in-memory adapter too:
+// equal scores must rank identically on both.
+//
+// Every statement is spelled out in full rather than assembled from a column list, so
+// that no statement is ever *constructed*: the only values that reach SQL are bound
+// parameters.
+const SEARCH = {
+    cosine: `SELECT ${COLUMNS}, 1 - (embedding <=> $1::vector) AS score FROM aid_chunks ` +
+        'ORDER BY embedding <=> $1::vector, chunk_id LIMIT $2',
+    dot: `SELECT ${COLUMNS}, -(embedding <#> $1::vector) AS score FROM aid_chunks ` +
+        'ORDER BY embedding <#> $1::vector, chunk_id LIMIT $2',
+    l2: `SELECT ${COLUMNS}, -(embedding <-> $1::vector) AS score FROM aid_chunks ` +
+        'ORDER BY embedding <-> $1::vector, chunk_id LIMIT $2',
+};
+const requireFromHere = createRequire(import.meta.url);
+/** Import the optional driver, or explain how to install it. */
+function loadDriver() {
+    try {
+        return requireFromHere(DRIVER);
+    }
+    catch {
+        throw new ConfigurationError('the pgvector store needs its driver; install it with `pnpm add pg` in the ' +
+            'generated app (the default runtime install omits it)');
+    }
+}
+/**
+ * Resolve an `env:NAME` reference to the variable's value.
+ *
+ * An `env:` reference names a variable, not an alias: nothing here reaches the model
+ * catalog, so resolving it at run time cannot silently change which store a run wrote
+ * to.
+ */
+export function resolveUri(uri) {
+    if (uri === null || uri === undefined) {
+        throw new ConfigurationError('the pgvector store requires a uri');
+    }
+    if (!uri.startsWith(ENV_PREFIX)) {
+        return uri;
+    }
+    const name = uri.slice(ENV_PREFIX.length);
+    if (name.length === 0) {
+        throw new ConfigurationError(`store uri ${repr(uri)} names an empty environment variable`);
+    }
+    const value = process.env[name];
+    if (value === undefined) {
+        throw new ConfigurationError(`store uri ${repr(uri)} refers to environment variable ${repr(name)}, which is unset`);
+    }
+    return value;
+}
+/**
+ * A float as Python's `repr` spells it, so the literal form matches the Python adapter.
+ *
+ * `String(-0)` is `'0'`, but `repr(-0.0)` is `'-0.0'`; the sign is part of the literal
+ * Python emits, and a bare `0.0` would be a visible divergence. The very large
+ * magnitudes where Python's shortest-repr algorithm switches to exponent notation
+ * earlier than `Number#toString` are not reproduced -- no embedding component reaches
+ * them, and reproducing the algorithm would be a lie dressed as fidelity.
+ */
+function floatRepr(value) {
+    if (Object.is(value, -0))
+        return '-0.0';
+    const text = String(value);
+    return /[.eEn]/.test(text) ? text : `${text}.0`;
+}
+/** pgvector's text input format, so its own package is not a dependency. */
+export function vectorLiteral(vector) {
+    return `[${vector.map((value) => floatRepr(value)).join(',')}]`;
+}
+/** Accept either a driver-returned sequence or pgvector's text form. */
+export function parseVector(value) {
+    if (typeof value === 'string') {
+        const stripped = value.trim().replace(/^\[/, '').replace(/\]$/, '');
+        if (stripped.length === 0)
+            return [];
+        return stripped.split(',').map((part) => Number.parseFloat(part));
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => Number(item));
+    }
+    throw new ConfigurationError('cannot read a vector: expected a sequence or its text form');
+}
+function metadataFrom(value) {
+    if (typeof value === 'string') {
+        if (value.length === 0)
+            return {};
+        const parsed = JSON.parse(value);
+        return (parsed ?? {});
+    }
+    return (value ?? {});
+}
+/** A single-table store: one row per chunk, keyed by content hash. */
+export class PgVectorStore {
+    _uri;
+    _dimensions;
+    _connection = null;
+    _closed = false;
+    constructor(options) {
+        this._uri = resolveUri(options.uri);
+        this._dimensions = options.dimensions ?? null;
+    }
+    get kind() {
+        return 'pgvector';
+    }
+    async upsert(records) {
+        if (this._dimensions !== null) {
+            for (const record of records) {
+                if (record.vector.length !== this._dimensions) {
+                    throw new ConfigurationError(`store is pinned to ${this._dimensions} dimensions but a record carries ` +
+                        `${record.vector.length}`);
+                }
+            }
+        }
+        if (records.length === 0)
+            return 0;
+        const connection = await this.connect();
+        for (const record of records) {
+            await connection.query(UPSERT, this.params(record));
+        }
+        return records.length;
+    }
+    async search(vector, options) {
+        if (options.topK < 1) {
+            throw new ConfigurationError('top_k must be at least 1');
+        }
+        const statement = SEARCH[options.metric];
+        if (statement === undefined) {
+            throw new ConfigurationError(`pgvector cannot rank by ${repr(options.metric)}`);
+        }
+        const connection = await this.connect();
+        const { rows } = await connection.query(statement, [vectorLiteral(vector), options.topK]);
+        return rows.map((row) => new SearchHit({ record: this.record(row), score: Number(row[9]) }));
+    }
+    async corpus() {
+        const connection = await this.connect();
+        const { rows } = await connection.query(CORPUS);
+        return rows.map((row) => this.record(row));
+    }
+    async close() {
+        if (this._closed)
+            return;
+        this._closed = true;
+        if (this._connection !== null) {
+            await this._connection.end();
+            this._connection = null;
+        }
+    }
+    async connect() {
+        if (this._closed) {
+            throw new ConfigurationError('this store has been closed');
+        }
+        if (this._connection === null) {
+            const driver = loadDriver();
+            try {
+                this._connection = new driver.Client({ connectionString: this._uri });
+            }
+            catch (error) {
+                throw new ProviderError(`cannot connect to the pgvector store: ${String(error)}`);
+            }
+            await this.ensureSchema(this._connection);
+        }
+        return this._connection;
+    }
+    async ensureSchema(connection) {
+        await connection.query(CREATE_EXTENSION);
+        await connection.query(CREATE_TABLE);
+    }
+    params(record) {
+        const chunk = record.chunk;
+        return [
+            chunk.chunkId,
+            chunk.docId,
+            chunk.uri,
+            chunk.index,
+            chunk.start,
+            chunk.end,
+            chunk.text,
+            dumpsSorted(chunk.metadata),
+            vectorLiteral(record.vector),
+        ];
+    }
+    record(row) {
+        return new StoreRecord({
+            chunk: new Chunk({
+                chunkId: String(row[0]),
+                docId: String(row[1]),
+                uri: String(row[2]),
+                index: Number(row[3]),
+                start: Number(row[4]),
+                end: Number(row[5]),
+                text: String(row[6]),
+                metadata: metadataFrom(row[7]),
+            }),
+            vector: parseVector(row[8]),
+        });
+    }
+}
+//# sourceMappingURL=pgvector.js.map

package/dist/retrieval/pgvector.js.map

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

package/dist/retrieval/rerank.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Reordering a retrieved set before it is returned.
+ *
+ * Exactly one reranker exists in Phase 1, and it is lexical. That is a deliberate
+ * limitation rather than an unfinished one: the seam is what this layer owes, and the
+ * deterministic implementation is what lets a gate assert on ranking behaviour
+ * without an API key or a floating cross-encoder.
+ *
+ * Why rerank at all when hybrid search already blends two rankings? Because fusion
+ * answers "which candidates are worth considering" and reranking answers "which of
+ * these best answers the question", and the second question can look at the query and
+ * one passage together instead of at ranks alone. The lexical reranker does that with
+ * query-term coverage, which is cheap, explainable, and stable.
+ *
+ * The reranker **replaces** each item's score instead of adding a second number. After
+ * reranking, the number that ranks the list is the reranker's, and keeping a fused RRF
+ * value in the same field would put two incomparable scales in one place. Ranks are
+ * renumbered from 1 so {@link RetrievalResult.context} stays resolvable.
+ */
+import { RetrievedItem } from './citations.js';
+import type { RerankSpec } from './types.js';
+/**
+ * How much of `query` the passage actually covers, in `[0, 1]`.
+ *
+ * Query-term coverage, not term frequency: for "which passages answer this", a
+ * passage containing each distinct query term once is as good a candidate as one
+ * repeating a term, and rewarding repetition is how a keyword-stuffed chunk wins. An
+ * exact phrase match breaks ties toward the passage quoting the query.
+ */
+export declare function lexicalScore(query: string, text: string): number;
+/** Reorder candidates for a query, deterministically. */
+export interface Reranker {
+    readonly name: string;
+    rerank(query: string, items: readonly RetrievedItem[], init: {
+        readonly topN: number;
+    }): Promise<readonly RetrievedItem[]>;
+}
+/** Coverage-based reranking, with ties broken on chunk id. */
+export declare class LexicalReranker implements Reranker {
+    private readonly _name;
+    constructor(init?: {
+        readonly name?: string;
+    });
+    get name(): string;
+    rerank(query: string, items: readonly RetrievedItem[], init: {
+        readonly topN: number;
+    }): Promise<readonly RetrievedItem[]>;
+}
+/**
+ * The reranker a retriever's `rerank` block asks for, if any.
+ *
+ * `rerank.model` is free-form in the IR, and Phase 1 ships exactly one
+ * implementation. A declared model outside the lexical family is refused rather than
+ * quietly served by {@link LexicalReranker}, for the same reason an unimplemented
+ * source kind or store kind is refused: a retriever that appears to rerank with a
+ * cross-encoder it never called is worse than one that says it cannot. The guard
+ * matches on the name because the name is the only signal the IR gives; the lexical
+ * family is what this runtime can honestly claim.
+ */
+export declare function rerankerFor(spec: RerankSpec | null): Reranker | null;
+//# sourceMappingURL=rerank.d.ts.map

package/dist/retrieval/rerank.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rerank.d.ts","sourceRoot":"","sources":["../../src/retrieval/rerank.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,EAAQ,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAErD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI7C;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAgBhE;AAED,yDAAyD;AACzD,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,MAAM,CACJ,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,IAAI,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAC9B,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAAC;CACtC;AAED,8DAA8D;AAC9D,qBAAa,eAAgB,YAAW,QAAQ;IAC9C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B,YAAY,IAAI,GAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,EAEhD;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAEK,MAAM,CACV,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,IAAI,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAC9B,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CA2BnC;CACF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,QAAQ,GAAG,IAAI,CASpE"}