/**
 * Metric-bound relevance (mmnto-ai/totem#2738).
 *
 * A distance is only interpretable against the metric that produced it. The
 * pre-#2738 code hard-coded `1 / (1 + _distance)` at the row-mapping site with
 * no record of which metric LanceDB had actually used, so a metric change
 * anywhere would have silently re-scaled every relevance number in the system.
 * This module makes the metric a named fact and the normalization a map keyed
 * by it: one truth, stated once, quoted in the doc comments below from the
 * LanceDB SDK's own definitions.
 */
/** The distance metrics the LanceDB TypeScript SDK can be asked for (`VectorQuery.distanceType`). */
export type DistanceMetric = 'l2' | 'cosine' | 'dot';
/**
 * Every spelling the SDK accepts — the allow-list `assertDistanceMetric` gates on.
 * Frozen at runtime as well as `readonly` in the type: a JS caller that pushed a
 * spelling onto it would otherwise pass the gate and reach an undefined map entry
 * (CodeRabbit on mmnto-ai/totem#2761).
 */
export declare const DISTANCE_METRICS: readonly DistanceMetric[];
/**
 * The ONE metric every Totem vector query is issued with (mmnto-ai/totem#2738).
 *
 * Both query sites in `lance-search.ts` chain `.distanceType(VECTOR_DISTANCE_METRIC)`
 * explicitly, so the metric is a recorded fact in the query rather than the SDK
 * default it happens to coincide with. `runSync` also records it in
 * `.totem/index-manifest.json` as `vectorDistanceMetric`.
 */
export declare const VECTOR_DISTANCE_METRIC: DistanceMetric;
/**
 * Why a computed relevance can leave [0, 1] — the cause is METRIC-SPECIFIC
 * (mmnto-ai/totem#2738 falsification round, F1), so the warning must not name a
 * cause the metric cannot have.
 *
 * Under `l2` the SDK returns a squared distance, which is `≥ 0` by
 * construction, so `1 / (1 + d) ∈ (0, 1]` for every value the SDK can legally
 * return: a breach there is NOT a non-unit-norm embedder, it is a fault. And it
 * is always a NEGATIVE, FINITE `_distance` — the search layer discards a
 * non-finite `_distance` BEFORE the map runs (both the row-mapping site and the
 * pre-fusion tally require `Number.isFinite`), so a non-finite value produces no
 * relevance at all and can never reach this warning. The string names only what
 * the warning can actually report (fold 2, F1).
 *
 * Under `cosine` / `dot` the mapping DOES leave [0, 1] for vectors that are not
 * unit-norm, which is the real embedder-profile signal.
 */
export declare const OUT_OF_RANGE_CAUSE: Record<DistanceMetric, string>;
/**
 * Narrow an untrusted value (a manifest field, a config key, a record read off
 * disk) to a `DistanceMetric`, or throw loudly naming the value and every
 * allowed spelling. The type makes an unmapped metric unreachable in code; this
 * is the runtime gate for values that did not come through the type.
 */
export declare function assertDistanceMetric(value: unknown): DistanceMetric;
/**
 * Normalize a LanceDB `_distance` into a relevance under the given metric.
 *
 * A pure map with one job: it never warns, never throws ON RANGE, and never
 * clamps. The caller judges the result with {@link isRelevanceInRange} and
 * decides what a range breach means at that call site.
 *
 * The METRIC is gated: `assertDistanceMetric` runs first (mmnto-ai/totem#2738
 * falsification round, F5), so a spelling that reached here past the type — an
 * `any`, a value read off a record, a JS caller — raises the named
 * `TotemError` instead of a bare `TypeError` from an undefined map entry.
 */
export declare function relevanceFromDistance(metric: DistanceMetric, distance: number): number;
/** Whether a relevance is a finite number inside the closed interval [0, 1]. */
export declare function isRelevanceInRange(relevance: number): boolean;
//# sourceMappingURL=relevance.d.ts.map