/**
 * Grounding-bundle assembly (mmnto-ai/totem#2101, strategy#474 slice 2).
 *
 * The bundle is the per-item provenance record for everything the
 * deterministic layer DELIVERED into a run's prompt: each item names what it
 * is (`sourceType` + `filePath` + optional `sourceRepo`), what it contained
 * (`contentHash` — identity, never bytes), and HOW it was obtained
 * (`provenance` class). The first cut wraps similarity retrieval honestly as
 * `similarity-only`; structural resolvers (mmnto-ai/totem#344/#375) graduate items to
 * `structurally-verified` by supplying them explicitly — this builder can
 * never upgrade a class on its own (honest-absent: nothing upgrades
 * provenance silently).
 *
 * Assembly is caller-side (the deterministic layer) — providers stay dumb
 * pipes. The bundle is what `grounding.hash` attests: the DELIVERED items with
 * their measured relevance (mmnto-ai/totem#2700). Items are canonically sorted
 * here BECAUSE the hash is order-significant for arrays and retrieval order is
 * score-dependent — the sort is what makes two runs over the same delivered
 * set hash alike.
 */
import { type GroundingBundle } from './schema.js';
/**
 * One retrieved evidence item as the caller holds it — the `result` shape is
 * the identity-relevant subset of `SearchResult`, kept structural so callers
 * and tests don't need a full store hit to build one.
 */
export interface GroundingSourceItem {
    /** Retrieval partition the item entered the prompt under (`spec` | `session_log` | `code` | `lesson`). */
    sourceType: string;
    result: {
        content: string;
        filePath: string;
        /** Linked-index name for cross-repo hits; absent = the run's own repo (strategy review F1 on mmnto-ai/totem#2101). */
        sourceRepo?: string | undefined;
        /**
         * The vector-leg relevance from `relevanceFromDistance(VECTOR_DISTANCE_METRIC,
         * _distance)`; on unit-norm vectors under `l2` it lies in [0.2, 1]; the schema
         * bounds it to [0, 1] and the bundle omits a value outside it
         * (mmnto-ai/totem#2700, metric-bound in mmnto-ai/totem#2738). Absent when the
         * hit had no vector leg (FTS-only) — absence is the honest disclosure, never
         * a zero.
         */
        relevance?: number | undefined;
    };
}
/**
 * Map retrieved items into a canonical grounding bundle. Every input item is
 * included — duplicates are delivery records, not noise (the bundle records
 * what entered the prompt, and a snippet delivered twice was delivered
 * twice). All items are classed `similarity-only`: this is the first-cut
 * wrapper around the existing retrieval, and the ONLY class this builder can
 * emit by construction.
 *
 * A hit's vector-leg `relevance` is carried onto its item ONLY when it is a
 * finite number IN [0, 1] (mmnto-ai/totem#2700; the range arm added by the
 * mmnto-ai/totem#2738 falsification round, F2) — an FTS-only hit carries none,
 * and the absence is the disclosure. The value rides the item through the
 * canonical sort, so no index correspondence with the input array is ever
 * needed.
 *
 * The range check is HERE rather than left to the schema because the schema
 * bound (`relevance: z.number().min(0).max(1)`) THROWS at the artifact write,
 * which would turn the search layer's "warn, never throw" contract into a hard
 * failure one layer down: an out-of-range relevance would have killed the run
 * that the search deliberately returned unchanged. The search layer has
 * already warned once about the breach by the time a value reaches here, so
 * the honest record is the item WITHOUT a relevance — the same absence an
 * FTS-only hit carries, and never a clamped number that would launder a fault
 * into a plausible-looking measurement.
 *
 * The record loses the distinction on purpose; the JUDGMENT keeps it. The
 * CLI's `evaluateGroundingFloor` applies this same predicate to the raw hit
 * and counts an FTS-only absence as floor-exempt (one saves a run) but a
 * faulted value as neither signal nor exemption — a fault never saves a run
 * (mmnto-ai/totem#2761 bot round, CodeRabbit + Greptile P1).
 */
export declare function buildGroundingBundle(items: GroundingSourceItem[]): GroundingBundle;
/**
 * Derive the artifact's `provenanceSummary` from the bundle — never asserted
 * wholesale (derive-or-couple: a stored summary is a mirror that can drift
 * from `items`). Sorted class-count string (`similarity-only:14`,
 * `compiled-rule:1,similarity-only:2`) so the eval harness can threshold on
 * it deterministically; zero items → `'ungrounded'` (abstention named, not
 * silent — Tenet 14 honest-absent).
 */
export declare function summarizeProvenance(bundle: GroundingBundle): string;
//# sourceMappingURL=grounding.d.ts.map