@whyparabola/cabar 0.0.0-stage → 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,255 @@
+import { T as TokenCounter, S as Similarity, C as CabarSelectResult, a as CabarUnit, b as CabarSelectOptions } from './cabar-B-R-rHby.cjs';
+export { A as ADAPTIVE_DEFAULTS, c as CHAR4_COUNTER, d as CabarDecision, e as CabarSelector, f as CabarStats, D as DEFAULTS, g as DEFAULT_RECENCY_DECAY_DAYS, h as cosineSimilarity, i as embeddingSimilarity, j as estimateTokens, r as recencyDecay } from './cabar-B-R-rHby.cjs';
+
+/**
+ * PrismSelector: CABAR-2 multi-fidelity budgeted selection.
+ *
+ * Where CabarSelector answers "which units do we spend verbatim budget
+ * on, and summarize the rest", Prism answers the finer question "at WHICH
+ * FIDELITY do we render each unit". It solves a Multiple-Choice Knapsack
+ * Problem (MCKP): each unit offers a small menu of renderings — verbatim /
+ * extract / claims / mention — with distinct (cost, utility) points, and the
+ * selector greedily packs marginal-utility-per-token, allowed to UPGRADE an
+ * already-selected unit to a costlier fidelity when that upgrade is the densest
+ * feasible move. All-or-nothing (CABAR-1) is the special case of a two-point
+ * menu {verbatim, absent}; Prism dominates it under tight budgets by trading a
+ * verbatim unit for several cheaper-fidelity units that together carry more.
+ *
+ * Design invariants (same purity contract as CabarSelector):
+ *   - PURE + deterministic: no LLM, no I/O, no Date.now — the caller supplies
+ *     `now`; `claims` are pre-fetched onto the units by the caller.
+ *   - Provider-agnostic token cost: the injectable `TokenCounter` defaults to
+ *     the shared char/4 estimator (prod), and benchmarks inject a real BPE
+ *     counter. Selection logic never assumes a specific vocabulary.
+ *   - Cache-stable OUTPUT ORDERING: selected units are emitted by
+ *     (timestamp asc, id asc), NOT by score, so the same units land in the same
+ *     prompt slots turn-over-turn (KV-cache friendly).
+ *   - β-hysteresis: an optional per-unit bonus for re-selecting a unit at
+ *     ≥ its previous fidelity (keeps prompts stable turn-over-turn). Defaults
+ *     to 0, a no-op.
+ *   - Answer-lossless FLOOR: every unit at or above `tauFloor` that misses the
+ *     budget still gets a mention line in the tail, so nothing recallable is
+ *     silently dropped.
+ */
+
+/** The four rendering fidelities, most→least faithful. */
+type Fidelity = 'verbatim' | 'extract' | 'claims' | 'mention';
+/** A retrieved unit plus its caller-pre-fetched claims (the CabarUnit + claims). */
+interface PrismUnit {
+    id: string;
+    content: string;
+    /** Relevance from your retriever, normalized to [0,1] (top item ideally 1.0). */
+    score: number;
+    timestamp?: Date;
+    /** Pre-resolved claim strings; enables the CLAIMS fidelity. Selector never fetches these. */
+    claims?: string[];
+    /** Optional vector for `similarity: embeddingSimilarity`. */
+    embedding?: ArrayLike<number>;
+}
+/** Per-fidelity multipliers φ(f) — how much utility a fidelity retains vs verbatim. */
+type FidelityFactors = Record<Fidelity, number>;
+interface PrismSelectOptions {
+    /** Token budget for the guaranteed block + selected renderings. The tail is capped separately by tailBudgetTokens. */
+    budgetTokens?: number;
+    /** Hard cap on DISTINCT units selected (upgrades do not count against it). */
+    maxUnits?: number;
+    /** Hard token cap for the mention-line tail (separate from budgetTokens). */
+    tailBudgetTokens?: number;
+    /** Minimum score for a unit to earn a tail mention line (below this: dropped). */
+    tauFloor?: number;
+    /** ρ = recencyLambda·decay + (1−recencyLambda). 0 ⇒ ρ≡1 (multi-session safe). */
+    recencyLambda?: number;
+    /** Recency scale in days for the exponential decay e^(-age/days). Default 365. */
+    recencyDecayDays?: number;
+    /** Blend on the novelty term: effectiveNovelty = 1 − noveltyWeight·(1 − novelty). */
+    noveltyWeight?: number;
+    /** Tokens pre-charged against budgetTokens before selection (e.g. resolved-claims block). */
+    guaranteedTokens?: number;
+    /** Deterministic "current time" for recency. Defaults to `new Date()`. */
+    now?: Date;
+    /** Injectable token cost model. Defaults to the shared char/4 estimator. */
+    tokenCounter?: TokenCounter;
+    /**
+     * Unit-level similarity used for novelty, in [0, 1]. Defaults to word-set
+     * Jaccard between the renderings. Pass `embeddingSimilarity` to catch paraphrases.
+     */
+    similarity?: Similarity<PrismUnit>;
+    /** Per-fidelity utility multipliers φ. Merged over defaults. */
+    fidelityFactors?: Partial<FidelityFactors>;
+    /** β — multiplicative bonus ×(1+β) for re-selecting a unit at ≥ prev fidelity. */
+    hysteresisBonus?: number;
+    /** Prior turn's selection (unit → fidelity) for the β-hysteresis predicate. */
+    prevSelected?: Array<{
+        unitId: string;
+        fidelity: Fidelity;
+    }>;
+    /**
+     * Adaptive stopping mode. When true, ADD-move admission
+     * (a unit newly entering the selection) is gated: past `minKeep` distinct
+     * units, a unit may only be ADD-admitted if its relevance fraction (score /
+     * top-candidate score) is >= `relFloor` AND the candidate rendering's
+     * novelty vs the already-chosen renderings is >= `novFloor`. UPGRADE moves
+     * and the mention-tail are unaffected. `maxCeilingTokens` replaces
+     * `budgetTokens` as the only hard token bound (`maxUnits` is ignored).
+     * Default false: behavior is byte-identical to the fixed-budget path.
+     */
+    adaptive?: boolean;
+    /** Adaptive mode: distinct units ADD-admitted before the relFloor/novFloor gate applies. Default 3. */
+    minKeep?: number;
+    /** Adaptive mode: below this fraction of the top candidate's score, ADD admission stops. Default 0.4. */
+    relFloor?: number;
+    /** Adaptive mode: below this novelty vs chosen renderings, ADD admission stops. Default 0.2. */
+    novFloor?: number;
+    /** Adaptive mode: hard token ceiling — replaces budgetTokens as the bound. Default 4000. */
+    maxCeilingTokens?: number;
+}
+interface PrismSelectedUnit {
+    unit: PrismUnit;
+    fidelity: Fidelity;
+    rendered: string;
+    tokens: number;
+}
+interface PrismStats {
+    /** Sum of every candidate unit's VERBATIM cost (the pre-selection ceiling). */
+    candidateTokens: number;
+    selectedTokens: number;
+    tailTokens: number;
+    budgetTokens: number;
+    /** guaranteedTokens + selectedTokens + tailTokens — actual spend vs budgetTokens. */
+    utilizedTokens: number;
+    fidelityHistogram: Record<Fidelity, number>;
+    /** Number of greedy moves applied (adds + upgrades). */
+    moves: number;
+}
+interface PrismSelectResult {
+    selected: PrismSelectedUnit[];
+    /** Unselected units at or above tauFloor — floored into the mention tail. */
+    tail: PrismUnit[];
+    /** The rendered tail block (mention lines, or verbatim on the tiny-pool guard). */
+    tailBlock: string;
+    stats: PrismStats;
+}
+declare class PrismSelector {
+    /**
+     * MCKP-greedy multi-fidelity selection: build each unit's rendering menu,
+     * greedily apply the densest feasible ADD/UPGRADE move, run the KMN
+     * best-single swap, then floor the remainder into a mention tail.
+     */
+    static select(units: PrismUnit[], query: string, opts?: PrismSelectOptions): PrismSelectResult;
+}
+
+/**
+ * Prism renderings: deterministic multi-fidelity renderings of a retrieved
+ * unit (the CABAR-2 "Prism" extension of CABAR's all-or-nothing selection).
+ *
+ * CABAR-1 spent budget on a unit at a single fidelity (verbatim, or nothing —
+ * with an extractive tail for the rest). Prism turns that binary into a ladder:
+ * a unit can be rendered at VERBATIM (full content), EXTRACT (query-aware
+ * sentence extract, ≤~40% of verbatim tokens), CLAIMS (its pre-resolved claim
+ * bullets), or MENTION (a one-line dereferenceable pointer). The MCKP selector
+ * (PrismSelector) then picks per-unit fidelities to maximize utility under the
+ * token budget instead of dropping units wholesale.
+ *
+ * Every rendering here is PURE and deterministic: no LLM, no I/O, no clock.
+ * Costs are measured through an injected `TokenCounter` (char/4 by default,
+ * real BPE when you inject one) so the same code costs the same
+ * text the caller will bill for. Claims are pre-fetched by the caller and live
+ * on the unit — this module never fetches them.
+ */
+
+/** Lowercased word (3+ chars) token set — same family as CabarSelector.tokenize. */
+declare function tokenize(text: string): Set<string>;
+declare function jaccard(a: Set<string>, b: Set<string>): number;
+/** Sentence split — same regex family as CabarSelector.buildTailSummary. */
+declare function splitSentences(text: string): string[];
+/**
+ * Word-boundary truncation to a token budget, appending an ellipsis only when
+ * the text is actually cut. Uses the injected counter so the cut respects the
+ * caller's tokenization (char/4 or BPE). Always keeps at least the first word.
+ */
+declare function truncateToTokens(text: string, maxTokens: number, counter: TokenCounter): string;
+/** VERBATIM — the unit's full content, unchanged. */
+declare function verbatim(u: PrismUnit): string;
+/**
+ * EXTRACT — query-aware sentence extraction targeting ≤~40% of verbatim tokens.
+ *
+ * Sentences are scored by query-term overlap plus a first-sentence positional
+ * prior, deduped on normalized text, then greedily packed (highest score first,
+ * stable on original order) up to the ~40% token target. Selected sentences are
+ * emitted in ORIGINAL narrative order (unlike the score-ordered tail) so the
+ * extract reads coherently. Never returns empty for non-empty content: if the
+ * target is too small for any sentence, the single top-scored sentence is kept
+ * (a single-sentence unit thus extracts to itself, and is dropped later by the
+ * selector's cost-dominance guard rather than duplicating verbatim).
+ */
+declare function extract(u: PrismUnit, query: string, counter: TokenCounter): string;
+/**
+ * CLAIMS — the unit's pre-resolved claims as '- <claim>' bullet lines.
+ * UNAVAILABLE (null) when the caller pre-fetched no claims for this unit.
+ */
+declare function claimsRendering(u: PrismUnit): string | null;
+/**
+ * MENTION — a one-line dereferenceable pointer:
+ *   [<id>@<yyyy-mm-dd if timestamp>] <first sentence, ≤25 tokens>
+ * This is the answer-lossless floor: even a unit that loses the budget contest
+ * still leaves a citable trace the caller can dereference back to the full unit.
+ */
+declare function mention(u: PrismUnit, counter: TokenCounter): string;
+
+/**
+ * Score normalization. The selectors expect relevance in [0, 1] with the top
+ * candidate at (or near) 1.0: `tauFloor` and the adaptive relevance cliff are
+ * fractions of that scale. Raw retriever scores rarely are: cosine
+ * similarities bunch up in 0.7–0.85, BM25 and reranker logits are unbounded,
+ * and vector-store distances run the wrong way.
+ */
+interface NormalizeOptions {
+    /**
+     * - `minmax` (default): best → 1, worst → 0. Spreads bunched-up scores
+     *   (cosine similarities) across the full range.
+     * - `max`: divide by the best score. Keeps ratios between scores; only for
+     *   non-negative scores.
+     */
+    method?: 'minmax' | 'max';
+    /** Set to false for distances (lower = more relevant). Default true. */
+    higherIsBetter?: boolean;
+}
+/** Returns copies of the units with `score` mapped to [0, 1]. Input order is kept. */
+declare function normalizeScores<T extends {
+    score: number;
+}>(units: T[], opts?: NormalizeOptions): T[];
+
+/**
+ * Helpers around a selection result: turn it into prompt text, and compare it
+ * with what you send today (shadow mode).
+ */
+
+interface ToContextOptions {
+    /** Separator between selected units. Default: a blank line. */
+    separator?: string;
+    /** Heading put above the tail. Default: "Other possibly relevant notes:". Pass '' for none. */
+    tailHeading?: string;
+    /** Wraps each selected unit, e.g. to add ids or XML tags. Default: the text as is. */
+    format?: (text: string, id: string) => string;
+}
+/** Joins a CABAR or Prism result into one string to put in the prompt. */
+declare function toContext(result: CabarSelectResult | PrismSelectResult, opts?: ToContextOptions): string;
+interface ShadowReport {
+    /** Tokens of every unit you passed in (what "send everything" costs). */
+    sendAllTokens: number;
+    /** Tokens CABAR would send: selected + tail. */
+    cabarTokens: number;
+    /** 1 − cabarTokens / sendAllTokens. */
+    savedFraction: number;
+    selectedIds: string[];
+    tailIds: string[];
+    droppedIds: string[];
+    result: CabarSelectResult;
+}
+/**
+ * Shadow mode: run CABAR next to your current pipeline without changing what
+ * you send. Log the report, compare answers, then switch when you trust it.
+ */
+declare function shadowReport(units: CabarUnit[], query: string, opts?: CabarSelectOptions): ShadowReport;
+
+export { CabarSelectOptions, CabarSelectResult, CabarUnit, type Fidelity, type FidelityFactors, type NormalizeOptions, type PrismSelectOptions, type PrismSelectResult, type PrismSelectedUnit, PrismSelector, type PrismStats, type PrismUnit, type ShadowReport, Similarity, type ToContextOptions, TokenCounter, claimsRendering, extract, jaccard, mention, normalizeScores, shadowReport, splitSentences, toContext, tokenize, truncateToTokens, verbatim };

package/dist/index.d.ts

@@ -0,0 +1,255 @@
+import { T as TokenCounter, S as Similarity, C as CabarSelectResult, a as CabarUnit, b as CabarSelectOptions } from './cabar-B-R-rHby.js';
+export { A as ADAPTIVE_DEFAULTS, c as CHAR4_COUNTER, d as CabarDecision, e as CabarSelector, f as CabarStats, D as DEFAULTS, g as DEFAULT_RECENCY_DECAY_DAYS, h as cosineSimilarity, i as embeddingSimilarity, j as estimateTokens, r as recencyDecay } from './cabar-B-R-rHby.js';
+
+/**
+ * PrismSelector: CABAR-2 multi-fidelity budgeted selection.
+ *
+ * Where CabarSelector answers "which units do we spend verbatim budget
+ * on, and summarize the rest", Prism answers the finer question "at WHICH
+ * FIDELITY do we render each unit". It solves a Multiple-Choice Knapsack
+ * Problem (MCKP): each unit offers a small menu of renderings — verbatim /
+ * extract / claims / mention — with distinct (cost, utility) points, and the
+ * selector greedily packs marginal-utility-per-token, allowed to UPGRADE an
+ * already-selected unit to a costlier fidelity when that upgrade is the densest
+ * feasible move. All-or-nothing (CABAR-1) is the special case of a two-point
+ * menu {verbatim, absent}; Prism dominates it under tight budgets by trading a
+ * verbatim unit for several cheaper-fidelity units that together carry more.
+ *
+ * Design invariants (same purity contract as CabarSelector):
+ *   - PURE + deterministic: no LLM, no I/O, no Date.now — the caller supplies
+ *     `now`; `claims` are pre-fetched onto the units by the caller.
+ *   - Provider-agnostic token cost: the injectable `TokenCounter` defaults to
+ *     the shared char/4 estimator (prod), and benchmarks inject a real BPE
+ *     counter. Selection logic never assumes a specific vocabulary.
+ *   - Cache-stable OUTPUT ORDERING: selected units are emitted by
+ *     (timestamp asc, id asc), NOT by score, so the same units land in the same
+ *     prompt slots turn-over-turn (KV-cache friendly).
+ *   - β-hysteresis: an optional per-unit bonus for re-selecting a unit at
+ *     ≥ its previous fidelity (keeps prompts stable turn-over-turn). Defaults
+ *     to 0, a no-op.
+ *   - Answer-lossless FLOOR: every unit at or above `tauFloor` that misses the
+ *     budget still gets a mention line in the tail, so nothing recallable is
+ *     silently dropped.
+ */
+
+/** The four rendering fidelities, most→least faithful. */
+type Fidelity = 'verbatim' | 'extract' | 'claims' | 'mention';
+/** A retrieved unit plus its caller-pre-fetched claims (the CabarUnit + claims). */
+interface PrismUnit {
+    id: string;
+    content: string;
+    /** Relevance from your retriever, normalized to [0,1] (top item ideally 1.0). */
+    score: number;
+    timestamp?: Date;
+    /** Pre-resolved claim strings; enables the CLAIMS fidelity. Selector never fetches these. */
+    claims?: string[];
+    /** Optional vector for `similarity: embeddingSimilarity`. */
+    embedding?: ArrayLike<number>;
+}
+/** Per-fidelity multipliers φ(f) — how much utility a fidelity retains vs verbatim. */
+type FidelityFactors = Record<Fidelity, number>;
+interface PrismSelectOptions {
+    /** Token budget for the guaranteed block + selected renderings. The tail is capped separately by tailBudgetTokens. */
+    budgetTokens?: number;
+    /** Hard cap on DISTINCT units selected (upgrades do not count against it). */
+    maxUnits?: number;
+    /** Hard token cap for the mention-line tail (separate from budgetTokens). */
+    tailBudgetTokens?: number;
+    /** Minimum score for a unit to earn a tail mention line (below this: dropped). */
+    tauFloor?: number;
+    /** ρ = recencyLambda·decay + (1−recencyLambda). 0 ⇒ ρ≡1 (multi-session safe). */
+    recencyLambda?: number;
+    /** Recency scale in days for the exponential decay e^(-age/days). Default 365. */
+    recencyDecayDays?: number;
+    /** Blend on the novelty term: effectiveNovelty = 1 − noveltyWeight·(1 − novelty). */
+    noveltyWeight?: number;
+    /** Tokens pre-charged against budgetTokens before selection (e.g. resolved-claims block). */
+    guaranteedTokens?: number;
+    /** Deterministic "current time" for recency. Defaults to `new Date()`. */
+    now?: Date;
+    /** Injectable token cost model. Defaults to the shared char/4 estimator. */
+    tokenCounter?: TokenCounter;
+    /**
+     * Unit-level similarity used for novelty, in [0, 1]. Defaults to word-set
+     * Jaccard between the renderings. Pass `embeddingSimilarity` to catch paraphrases.
+     */
+    similarity?: Similarity<PrismUnit>;
+    /** Per-fidelity utility multipliers φ. Merged over defaults. */
+    fidelityFactors?: Partial<FidelityFactors>;
+    /** β — multiplicative bonus ×(1+β) for re-selecting a unit at ≥ prev fidelity. */
+    hysteresisBonus?: number;
+    /** Prior turn's selection (unit → fidelity) for the β-hysteresis predicate. */
+    prevSelected?: Array<{
+        unitId: string;
+        fidelity: Fidelity;
+    }>;
+    /**
+     * Adaptive stopping mode. When true, ADD-move admission
+     * (a unit newly entering the selection) is gated: past `minKeep` distinct
+     * units, a unit may only be ADD-admitted if its relevance fraction (score /
+     * top-candidate score) is >= `relFloor` AND the candidate rendering's
+     * novelty vs the already-chosen renderings is >= `novFloor`. UPGRADE moves
+     * and the mention-tail are unaffected. `maxCeilingTokens` replaces
+     * `budgetTokens` as the only hard token bound (`maxUnits` is ignored).
+     * Default false: behavior is byte-identical to the fixed-budget path.
+     */
+    adaptive?: boolean;
+    /** Adaptive mode: distinct units ADD-admitted before the relFloor/novFloor gate applies. Default 3. */
+    minKeep?: number;
+    /** Adaptive mode: below this fraction of the top candidate's score, ADD admission stops. Default 0.4. */
+    relFloor?: number;
+    /** Adaptive mode: below this novelty vs chosen renderings, ADD admission stops. Default 0.2. */
+    novFloor?: number;
+    /** Adaptive mode: hard token ceiling — replaces budgetTokens as the bound. Default 4000. */
+    maxCeilingTokens?: number;
+}
+interface PrismSelectedUnit {
+    unit: PrismUnit;
+    fidelity: Fidelity;
+    rendered: string;
+    tokens: number;
+}
+interface PrismStats {
+    /** Sum of every candidate unit's VERBATIM cost (the pre-selection ceiling). */
+    candidateTokens: number;
+    selectedTokens: number;
+    tailTokens: number;
+    budgetTokens: number;
+    /** guaranteedTokens + selectedTokens + tailTokens — actual spend vs budgetTokens. */
+    utilizedTokens: number;
+    fidelityHistogram: Record<Fidelity, number>;
+    /** Number of greedy moves applied (adds + upgrades). */
+    moves: number;
+}
+interface PrismSelectResult {
+    selected: PrismSelectedUnit[];
+    /** Unselected units at or above tauFloor — floored into the mention tail. */
+    tail: PrismUnit[];
+    /** The rendered tail block (mention lines, or verbatim on the tiny-pool guard). */
+    tailBlock: string;
+    stats: PrismStats;
+}
+declare class PrismSelector {
+    /**
+     * MCKP-greedy multi-fidelity selection: build each unit's rendering menu,
+     * greedily apply the densest feasible ADD/UPGRADE move, run the KMN
+     * best-single swap, then floor the remainder into a mention tail.
+     */
+    static select(units: PrismUnit[], query: string, opts?: PrismSelectOptions): PrismSelectResult;
+}
+
+/**
+ * Prism renderings: deterministic multi-fidelity renderings of a retrieved
+ * unit (the CABAR-2 "Prism" extension of CABAR's all-or-nothing selection).
+ *
+ * CABAR-1 spent budget on a unit at a single fidelity (verbatim, or nothing —
+ * with an extractive tail for the rest). Prism turns that binary into a ladder:
+ * a unit can be rendered at VERBATIM (full content), EXTRACT (query-aware
+ * sentence extract, ≤~40% of verbatim tokens), CLAIMS (its pre-resolved claim
+ * bullets), or MENTION (a one-line dereferenceable pointer). The MCKP selector
+ * (PrismSelector) then picks per-unit fidelities to maximize utility under the
+ * token budget instead of dropping units wholesale.
+ *
+ * Every rendering here is PURE and deterministic: no LLM, no I/O, no clock.
+ * Costs are measured through an injected `TokenCounter` (char/4 by default,
+ * real BPE when you inject one) so the same code costs the same
+ * text the caller will bill for. Claims are pre-fetched by the caller and live
+ * on the unit — this module never fetches them.
+ */
+
+/** Lowercased word (3+ chars) token set — same family as CabarSelector.tokenize. */
+declare function tokenize(text: string): Set<string>;
+declare function jaccard(a: Set<string>, b: Set<string>): number;
+/** Sentence split — same regex family as CabarSelector.buildTailSummary. */
+declare function splitSentences(text: string): string[];
+/**
+ * Word-boundary truncation to a token budget, appending an ellipsis only when
+ * the text is actually cut. Uses the injected counter so the cut respects the
+ * caller's tokenization (char/4 or BPE). Always keeps at least the first word.
+ */
+declare function truncateToTokens(text: string, maxTokens: number, counter: TokenCounter): string;
+/** VERBATIM — the unit's full content, unchanged. */
+declare function verbatim(u: PrismUnit): string;
+/**
+ * EXTRACT — query-aware sentence extraction targeting ≤~40% of verbatim tokens.
+ *
+ * Sentences are scored by query-term overlap plus a first-sentence positional
+ * prior, deduped on normalized text, then greedily packed (highest score first,
+ * stable on original order) up to the ~40% token target. Selected sentences are
+ * emitted in ORIGINAL narrative order (unlike the score-ordered tail) so the
+ * extract reads coherently. Never returns empty for non-empty content: if the
+ * target is too small for any sentence, the single top-scored sentence is kept
+ * (a single-sentence unit thus extracts to itself, and is dropped later by the
+ * selector's cost-dominance guard rather than duplicating verbatim).
+ */
+declare function extract(u: PrismUnit, query: string, counter: TokenCounter): string;
+/**
+ * CLAIMS — the unit's pre-resolved claims as '- <claim>' bullet lines.
+ * UNAVAILABLE (null) when the caller pre-fetched no claims for this unit.
+ */
+declare function claimsRendering(u: PrismUnit): string | null;
+/**
+ * MENTION — a one-line dereferenceable pointer:
+ *   [<id>@<yyyy-mm-dd if timestamp>] <first sentence, ≤25 tokens>
+ * This is the answer-lossless floor: even a unit that loses the budget contest
+ * still leaves a citable trace the caller can dereference back to the full unit.
+ */
+declare function mention(u: PrismUnit, counter: TokenCounter): string;
+
+/**
+ * Score normalization. The selectors expect relevance in [0, 1] with the top
+ * candidate at (or near) 1.0: `tauFloor` and the adaptive relevance cliff are
+ * fractions of that scale. Raw retriever scores rarely are: cosine
+ * similarities bunch up in 0.7–0.85, BM25 and reranker logits are unbounded,
+ * and vector-store distances run the wrong way.
+ */
+interface NormalizeOptions {
+    /**
+     * - `minmax` (default): best → 1, worst → 0. Spreads bunched-up scores
+     *   (cosine similarities) across the full range.
+     * - `max`: divide by the best score. Keeps ratios between scores; only for
+     *   non-negative scores.
+     */
+    method?: 'minmax' | 'max';
+    /** Set to false for distances (lower = more relevant). Default true. */
+    higherIsBetter?: boolean;
+}
+/** Returns copies of the units with `score` mapped to [0, 1]. Input order is kept. */
+declare function normalizeScores<T extends {
+    score: number;
+}>(units: T[], opts?: NormalizeOptions): T[];
+
+/**
+ * Helpers around a selection result: turn it into prompt text, and compare it
+ * with what you send today (shadow mode).
+ */
+
+interface ToContextOptions {
+    /** Separator between selected units. Default: a blank line. */
+    separator?: string;
+    /** Heading put above the tail. Default: "Other possibly relevant notes:". Pass '' for none. */
+    tailHeading?: string;
+    /** Wraps each selected unit, e.g. to add ids or XML tags. Default: the text as is. */
+    format?: (text: string, id: string) => string;
+}
+/** Joins a CABAR or Prism result into one string to put in the prompt. */
+declare function toContext(result: CabarSelectResult | PrismSelectResult, opts?: ToContextOptions): string;
+interface ShadowReport {
+    /** Tokens of every unit you passed in (what "send everything" costs). */
+    sendAllTokens: number;
+    /** Tokens CABAR would send: selected + tail. */
+    cabarTokens: number;
+    /** 1 − cabarTokens / sendAllTokens. */
+    savedFraction: number;
+    selectedIds: string[];
+    tailIds: string[];
+    droppedIds: string[];
+    result: CabarSelectResult;
+}
+/**
+ * Shadow mode: run CABAR next to your current pipeline without changing what
+ * you send. Log the report, compare answers, then switch when you trust it.
+ */
+declare function shadowReport(units: CabarUnit[], query: string, opts?: CabarSelectOptions): ShadowReport;
+
+export { CabarSelectOptions, CabarSelectResult, CabarUnit, type Fidelity, type FidelityFactors, type NormalizeOptions, type PrismSelectOptions, type PrismSelectResult, type PrismSelectedUnit, PrismSelector, type PrismStats, type PrismUnit, type ShadowReport, Similarity, type ToContextOptions, TokenCounter, claimsRendering, extract, jaccard, mention, normalizeScores, shadowReport, splitSentences, toContext, tokenize, truncateToTokens, verbatim };