@whyparabola/cabar 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aman Jha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,313 @@
-# Temporary Holding Version
+# CABAR
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Context-Budget-Aware Retrieval.** Your retriever found 24 chunks. CABAR decides which ones are actually worth the prompt tokens, sends those, and squeezes the rest into a short tail instead of dropping them.
+
+Pure TypeScript. Zero dependencies. No LLM calls, no I/O, embeddings optional. Deterministic: same input, same output.
+
+On LongMemEval-S it keeps **90% of the answer evidence with 79% fewer tokens**, where top-k at the same token spend keeps 79%. In a 72B-reader run on multi-session questions, accuracy went from **35% to 80%** with 84% fewer tokens, because the reader stopped drowning in context. ([Results](#results), including where it loses.)
+
+```
+npm install @whyparabola/cabar
+```
+
+---
+
+## The problem
+
+Most RAG and agent-memory pipelines do this:
+
+```ts
+const chunks = await retrieve(query, { topK: 24 });
+prompt += chunks.map((c) => c.content).join('\n'); // send everything
+```
+
+That costs you three ways:
+
+1. **Tokens.** Around 20k tokens per query in our memory system, mostly redundant.
+2. **Latency.** Answer time grows with prompt length. In our profile, ~80% of answer latency was the LLM reading context.
+3. **Accuracy.** Past a point, more context makes answers *worse*: the one fact that matters gets lost among near-duplicates and weak hits.
+
+Top-K truncation is not the fix. It keeps duplicates (two chunks saying the same thing both score high) and silently drops the long tail, where multi-session and temporal questions usually find their answer.
+
+## How CABAR works
+
+CABAR treats context as a **knapsack**: every chunk has a value and a token cost, and the prompt has a budget.
+
+```
+utility(u, S) = relevance(u) × recency(u) × novelty(u, S)
+```
+
+- **relevance**: the score from your retriever, normalized to [0, 1].
+- **recency**: `λ · e^(−age/365d) + (1 − λ)`. A gentle preference for newer chunks (λ = 0.3), never a cliff.
+- **novelty**: `1 − max Jaccard(u, s)` over chunks `s` already selected. Recomputed every round, so a near-duplicate of something already picked is worth almost nothing.
+
+Then:
+
+1. **Greedy fill by utility per token.** Each round, pick the chunk with the best marginal utility per token that still fits the budget.
+2. **Best-single swap.** If one chunk alone beats the whole greedy set, take it instead. This is the classic budgeted-max-coverage trick (Khuller, Moss & Naor) that gives greedy a constant-factor guarantee.
+3. **Adaptive stopping** (optional). After `minKeep` chunks, stop when the next candidate falls off a *relevance cliff* (below 40% of the top score) or adds too little novelty (< 0.2). Noisy pools stop early, and pools with a real relevant tail keep more. It doesn't look at the question type, only at the shape of the pool.
+4. **Summarize the tail, never drop it.** Every unselected chunk above `tauFloor` goes into a compact extractive summary: the sentences that overlap the query most, within a hard token cap. If that summary would cost more than the raw chunks, it sends the raw chunks instead.
+
+Selection is O(n · k²) similarity checks for n candidates and k selected: sub-millisecond for typical pools, negligible next to the LLM call it shrinks.
+
+### Prism: multi-fidelity (CABAR-2)
+
+CABAR's choice is binary: a chunk is sent in full or goes to the tail. **Prism** turns that into a ladder. Each chunk can be rendered at four fidelities:
+
+| Fidelity | What gets sent | Utility kept (default) |
+|---|---|---|
+| `verbatim` | the full chunk | 1.00 |
+| `extract` | query-relevant sentences, ≤ ~40% of the tokens | 0.85 |
+| `claims` | pre-extracted facts you attach to the chunk | 0.75 |
+| `mention` | a one-line pointer: `[id@date] first sentence…` | 0.30 |
+
+Prism solves this as a **multiple-choice knapsack**. Each move either adds a chunk at some fidelity or upgrades an already-selected chunk to a richer one, always taking the densest move. Under tight budgets it beats all-or-nothing, because three extracts often carry more than one verbatim chunk.
+
+Prism also emits selected chunks in **timestamp order, not score order**, so the same chunks land in the same prompt positions turn after turn. That keeps your provider's prompt cache warm. An optional hysteresis bonus (`hysteresisBonus`) makes it stick with last turn's choices for the same reason.
+
+## Usage
+
+```ts
+import { CabarSelector, normalizeScores, toContext } from '@whyparabola/cabar';
+
+const hits = await retrieve(query); // [{ id, content, score, timestamp? }]
+
+const result = CabarSelector.select(normalizeScores(hits), query); // ≤ 8 chunks, ≤ 4000 tokens
+const context = toContext(result); // selected chunks + "Other possibly relevant notes:" tail
+
+console.log(`${result.stats.candidateTokens} → ${result.stats.utilizedTokens} tokens`);
+```
+
+**Normalize your scores first.** CABAR expects relevance in [0, 1] with the best hit near 1. `tauFloor` and the adaptive cliff are fractions of that scale. Raw scores rarely fit:
+- Cosine similarities bunch up in 0.7–0.85, so nothing ever falls below `tauFloor`.
+- BM25 and reranker logits are unbounded.
+- Vector-store distances run the wrong way.
+
+`normalizeScores(hits)` maps any of them to [0, 1] (min-max by default). For distances, pass `{ higherIsBetter: false }`.
+
+**Start with the defaults.** In the evidence benchmarks below, fixed CABAR had the best balance of evidence kept and tokens spent.
+
+**Capped-adaptive** (`adaptive: true, capToMaxUnits: true`) saves more tokens (87% vs 79%) by stopping at the relevance cliff. The cost: it keeps less evidence verbatim (75% vs 90%), though most of the rest still reaches the prompt through the tail. How early it stops depends on the shape of your scores. Try it in shadow mode against your own pools before switching.
+
+### Vercel AI SDK (or any LLM call)
+
+```ts
+import { generateText } from 'ai';
+import { CabarSelector, normalizeScores, toContext } from '@whyparabola/cabar';
+
+const result = CabarSelector.select(normalizeScores(hits), question, { budgetTokens: 2000 });
+
+const { text } = await generateText({
+  model,
+  system: `Answer from these notes:\n\n${toContext(result, { format: (t, id) => `<note id="${id}">${t}</note>` })}`,
+  prompt: question,
+});
+```
+
+### LangChain.js
+
+`@whyparabola/cabar/langchain` is a document compressor. Drop it into `ContextualCompressionRetriever`:
+
+```ts
+import { ContextualCompressionRetriever } from '@langchain/classic/retrievers/contextual_compression'; // 'langchain/retrievers/contextual_compression' on LangChain 0.3
+import { CabarCompressor } from '@whyparabola/cabar/langchain';
+
+const retriever = new ContextualCompressionRetriever({
+  baseCompressor: new CabarCompressor({ budgetTokens: 2000 }),
+  baseRetriever: vectorStore.asRetriever(24),
+});
+```
+
+- **Scores:** it reads them from `metadata.relevance_score` or `metadata.score` and normalizes them. If they're missing, it falls back to the retriever's order.
+- **Tail:** it comes back as one extra `Document` with `metadata.cabar = 'tail'`. Pass `includeTail: false` to skip it.
+
+`@langchain/core` is an optional peer dependency.
+
+### Catch paraphrases with embeddings
+
+The default novelty check is word overlap, so it misses paraphrases. If your chunks already have embeddings, use those instead:
+
+```ts
+import { CabarSelector, embeddingSimilarity } from '@whyparabola/cabar';
+
+// each chunk: { id, content, score, embedding: number[] }
+const result = CabarSelector.select(chunks, query, { similarity: embeddingSimilarity });
+```
+
+Any `(a, b) => number` in [0, 1] works as `similarity`. It's available in both selectors.
+
+### Exact token counts
+
+```ts
+import { encode } from 'gpt-tokenizer';
+
+CabarSelector.select(chunks, query, { tokenCounter: { name: 'o200k', count: (t) => encode(t).length } });
+```
+
+### See why, and try it in shadow mode
+
+```ts
+import { CabarSelector, shadowReport } from '@whyparabola/cabar';
+
+const { decisions } = CabarSelector.select(chunks, query, { explain: true });
+// [{ id: 'u7', status: 'tail', reason: 'redundant with u2 (similarity 0.91)', tokens: 84, ... }, ...]
+
+const report = shadowReport(chunks, query); // doesn't change what you send
+log({ saved: report.savedFraction, dropped: report.droppedIds });
+```
+
+Shadow mode is the safe rollout:
+1. Keep sending what you send today.
+2. Log what CABAR would have sent.
+3. Compare answers on a sample, then switch.
+
+### Prism
+
+```ts
+import { PrismSelector, toContext } from '@whyparabola/cabar';
+
+const result = PrismSelector.select(chunksWithClaims, query, { budgetTokens: 2000 });
+for (const s of result.selected) console.log(s.unit.id, s.fidelity, s.rendered);
+const context = toContext(result);
+```
+
+Run the example: `npm run example` (source: [`examples/basic.ts`](examples/basic.ts)).
+
+## Options
+
+Both selectors share these (Prism's defaults in parentheses where different):
+
+| Option | Default | What it does |
+|---|---|---|
+| `budgetTokens` | 4000 | Token budget for `guaranteedTokens` + selected chunks |
+| `maxUnits` | 8 (12) | Max distinct chunks selected |
+| `tailBudgetTokens` | 600 | Hard cap for the tail, on top of the budget |
+| `tauFloor` | 0.15 | Chunks scoring below this are dropped, not summarized |
+| `recencyLambda` | 0.3 | 0 = ignore age entirely (safest for cross-session questions) |
+| `recencyDecayDays` | 365 | Scale of the exponential recency decay |
+| `noveltyWeight` | 1 | 0 = ignore redundancy, 1 = full MMR-style novelty |
+| `guaranteedTokens` | 0 | Tokens you've already spent (system prompt, a facts block), pre-charged against the budget |
+| `now` | `new Date()` | Pass a fixed date for reproducible results |
+| `tokenCounter` | chars / 4 | `{ name, count(text) }`, e.g. a real BPE tokenizer |
+| `similarity` | word-set Jaccard | `(a, b) => [0, 1]` for novelty, e.g. `embeddingSimilarity` |
+| `adaptive` | false | Enable the relevance-cliff/novelty stopping rule |
+| `minKeep` | 3 | Chunks kept before the adaptive rule can stop |
+| `relFloor` | 0.4 | Adaptive: stop below this fraction of the top score |
+| `novFloor` | 0.2 | Adaptive: stop below this novelty |
+| `maxCeilingTokens` | 4000 | Adaptive: the hard token bound (replaces `budgetTokens`) |
+| `capToMaxUnits` | false | CABAR only: adaptive also respects `maxUnits` |
+| `costExponent` | 1 | CABAR only: density = utility / tokens^x. Lower it (0.5) when answers live in long chunks |
+| `explain` | false | CABAR only: return `decisions`, the reason for every chunk |
+
+Prism only: `fidelityFactors`, `hysteresisBonus`, `prevSelected`, and `claims?: string[]` on each chunk.
+
+## Results
+
+### 1. Evidence recall on LongMemEval-S (reproducible, no LLM)
+
+[`bench/evidence-recall.ts`](bench/evidence-recall.ts) runs in about 10 seconds on the public [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned) dataset:
+1. For each of the 500 questions, a plain BM25 retriever pulls the top 24 chat turns from the haystack.
+2. Each selector picks from those 24 turns.
+3. The script counts how many of the turns LongMemEval marks as answer evidence survive, and what they cost.
+
+The 57 questions where BM25 missed all evidence are skipped, leaving 443. Full per-type tables: [`bench/longmemeval-results.md`](bench/longmemeval-results.md).
+
+| Selector | Evidence kept verbatim | All evidence kept | Evidence kept or in tail | Avg tokens | Tokens saved |
+|---|---|---|---|---|---|
+| Send all 24 | 100% | 100% | 100% | 6,756 | 0% |
+| Top-8 by score | 84.6% | 79.2% | 84.6% | 2,052 | 70% |
+| **CABAR (defaults)** | **90.3%** | **86.2%** | **93.6%** | **1,432** | **79%** |
+| Top-k at CABAR's token spend | 78.8% | 74.3% | 78.8% | 1,728 | 74% |
+| CABAR capped-adaptive | 75.1% | 66.8% | 91.6% | 890 | 87% |
+| Top-k at capped-adaptive's spend | 72.6% | 66.4% | 72.6% | 1,144 | 83% |
+| Prism (defaults) | 93.6% | 91.0% | 94.6% | 2,481 | 63% |
+
+- **Multi-session questions** (118), where the answer is spread across several sessions: CABAR keeps 87.8% of the evidence, top-k at the same spend 65.9%, top-8 75.5%. Removing duplicates makes room for the second and third piece of evidence.
+- **Where it loses:** on single-session-assistant questions (52), the evidence is usually one long assistant reply. CABAR ranks by utility *per token*, so it keeps 88.5% verbatim vs 94.2% for top-k (the tail still reaches 98.1%). Capped-adaptive drops to 61.5%.
+- **`costExponent: 0.5` fixes that case** (94.2%, level with top-k), but overall evidence drops to 88.8% and token savings to 73%. That's why it's an option, not the default.
+- BM25 plus min-max normalization is a weak, steep-scoring retriever. Your numbers will move with your retriever.
+
+### 2. Multi-hop evidence on HotpotQA (reproducible, no LLM)
+
+[`bench/hotpot-evidence.ts`](bench/hotpot-evidence.ts) runs in 4 seconds on all 7,405 dev questions (distractor setting):
+- Each question comes with 10 paragraphs: the 2 it needs and 8 distractors chosen to look relevant.
+- BM25 scores the 10 paragraphs, and each selector keeps k of them.
+- The script counts how often **both** gold paragraphs survive.
+
+Full table: [`bench/hotpot-results.md`](bench/hotpot-results.md).
+
+| Paragraphs kept | Top-k: both gold kept | CABAR: both gold kept | CABAR tokens vs top-k |
+|---|---|---|---|
+| 2 | 31.5% | **32.7%** | 22% fewer |
+| 3 | 48.1% | **50.6%** | 20% fewer |
+| 4 | 59.4% | **62.7%** | 17% fewer |
+
+Small but consistent: a few points more evidence on fewer tokens. The gain is much smaller than on LongMemEval because HotpotQA paragraphs come from different articles and rarely repeat each other, so there's little redundancy to remove. CABAR helps most where chunks overlap: chat logs, memory stores, tickets.
+
+### 3. Answer accuracy with a 72B reader (from MetaMemory)
+
+Measured inside MetaMemory, the agent-memory system CABAR was built for. Setup: LongMemEval-S, Qwen2.5-72B-Instruct-AWQ as reader and judge, tokens counted with o200k BPE.
+
+| Test set | Send everything | CABAR | Token reduction |
+|---|---|---|---|
+| Mixed, all question types (24 q) | 19/24 @ 7,780 tok | 19/24 @ 2,158 tok | 72% |
+| Multi-session (18 q) + abstention (2 q) | 7/20 @ 15,156 tok | **16/20** @ 2,406 tok | 84% |
+| Generic answer prompt, 6 types × 10 (60 q) | 40/60 @ 8,578 tok | **45/60** @ 2,051 tok | 76% |
+| Smoke test (6 q) | 6/6 @ 8,285 tok | 5/6 @ 2,064 tok | 75% |
+
+- **Adaptive CABAR:** on a rerun of the multi-session set it scored 16/20 at 2,137 tokens. On the 60-question set it scored 43/60 at 3,544.
+- **Prism:** 20/24 on the mixed set, but **13/20 on multi-session**, worse than plain CABAR there.
+- **Capped-adaptive:** checked only by which chunks it picks (on concentrated pools, exactly the same as fixed CABAR). Its accuracy wasn't benchmarked on its own.
+
+**Read these honestly:**
+- The samples are small: 20 questions gives a 95% interval of roughly ±20 points.
+- One reader model, one dataset.
+- This harness lives in MetaMemory, not in this repo.
+
+The direction is consistent (equal or better accuracy at a quarter of the tokens), but treat it as evidence, not a guarantee. Run CABAR in shadow mode on your own traffic first: log what it *would* send next to what you send now, and compare answers.
+
+### 4. Correctness
+
+[`test/properties.test.ts`](test/properties.test.ts) checks the guarantees on 500 random pools each:
+- The budget, `maxUnits` and the tail cap are never exceeded.
+- Output is deterministic.
+- Nothing at or above `tauFloor` is silently dropped.
+- An exact duplicate is never selected twice.
+- Prism always emits chunks in cache-stable order.
+
+On 30,000 random selections, this package produced byte-identical output to the original MetaMemory implementation.
+
+## When to use it
+
+**Good fit:**
+- Agent memory and RAG pipelines that retrieve 10–50 chunks per query.
+- Pools with lots of near-duplicate chunks (chat logs, memory stores, support tickets).
+- Anywhere prompt tokens cost you latency or money.
+
+**Not a fit:**
+- If you already send fewer than ~5 short chunks, there's little to trim.
+- Pools of distinct, non-overlapping documents gain only a little (see HotpotQA above).
+- Without `similarity: embeddingSimilarity`, novelty is lexical (word-set Jaccard), so paraphrases with different wording aren't caught.
+
+**Know the quirk:** the greedy fill ranks by utility *per token*, so it prefers short chunks. When one long chunk holds the answer (a long assistant reply, a big doc section), top-k can beat it: see single-session-assistant above. `costExponent: 0.5`, or chunking documents to similar sizes, keeps this in check.
+
+## Design rules
+
+- **Pure and deterministic.** No clock reads (pass `now`), no network, no randomness. The same pool always yields the same prompt, which makes it replayable and testable.
+- **Provider-agnostic.** The default token cost is `chars / 4`. Inject a real tokenizer when you need exact numbers.
+- **Never silently drop something relevant.** Anything above `tauFloor` that misses the budget still reaches the prompt, as a summary sentence (CABAR) or a mention line (Prism).
+
+## Development
+
+```
+npm install
+npm test          # 100 tests (unit + property)
+npm run typecheck
+npm run build     # ESM + CJS + types into dist/
+npx tsx bench/evidence-recall.ts longmemeval_s_cleaned.json
+npx tsx bench/hotpot-evidence.ts hotpot_dev_distractor_v1.json
+```
+
+## License
+
+[MIT](LICENSE) © Aman Jha. Built for MetaMemory, extracted as a standalone library.

package/dist/cabar-B-R-rHby.d.cts

@@ -0,0 +1,202 @@
+/**
+ * Small shared helpers: the default token estimator and the recency decay curve.
+ */
+/**
+ * Token-count heuristic: ~4 characters per token.
+ *
+ * Not a real tokenizer. Deliberately cheap and provider-agnostic (no
+ * dependency on any one model's BPE vocabulary): good enough for budget
+ * heuristics, not for exact billing. Pass your own `TokenCounter` to either
+ * selector when you need exact counts.
+ */
+declare function estimateTokens(text: string): number;
+/**
+ * A pluggable token counter. Defaults to the char/4 estimator; inject a real
+ * BPE tokenizer (e.g. `gpt-tokenizer`, tiktoken) for exact costs.
+ */
+interface TokenCounter {
+    name: string;
+    count(text: string): number;
+}
+/** Provider-agnostic default counter: the char/4 heuristic. */
+declare const CHAR4_COUNTER: TokenCounter;
+/**
+ * Similarity between two units in [0, 1], used for the novelty term in place
+ * of the built-in word-set Jaccard. 1 = same content, 0 = unrelated.
+ */
+type Similarity<T> = (a: T, b: T) => number;
+/** Cosine similarity of two equal-length vectors, clamped to [0, 1]. */
+declare function cosineSimilarity(a: ArrayLike<number>, b: ArrayLike<number>): number;
+/**
+ * Ready-made `similarity` option: cosine over each unit's `embedding`.
+ * Catches paraphrases that word overlap misses. Throws if a unit has no embedding.
+ */
+declare function embeddingSimilarity<T extends {
+    id: string;
+    embedding?: ArrayLike<number>;
+}>(a: T, b: T): number;
+/** Default recency scale in days: score = e^(-age / 365). */
+declare const DEFAULT_RECENCY_DECAY_DAYS = 365;
+/**
+ * Exponential recency decay in [0, 1]: 1 = brand new, → 0 as the unit ages.
+ * score = e^(-ageInDays / decayDays)
+ */
+declare function recencyDecay(ageInDays: number, decayDays?: number): number;
+
+/**
+ * CabarSelector: Context-Budget-Aware Retrieval.
+ *
+ * Pure, deterministic selection of which retrieved units are worth spending
+ * prompt-token budget on, replacing "take the top-K by score" with a greedy
+ * utility/cost knapsack:
+ *
+ *   utility(u, S) = relevance(u) × recency(u) × novelty(u, S)
+ *
+ * where S is the set already selected (novelty is recomputed against the
+ * CURRENT S on every iteration, so a second near-duplicate of an already-picked
+ * unit contributes ~0 marginal utility and is skipped in favor of budget spent
+ * elsewhere). Units below `tauFloor` relevance are dropped entirely; units at
+ * or above the floor that don't make the cut are extractively summarized into
+ * a compact `tailSummary` instead of being discarded outright.
+ *
+ * No LLM calls, no I/O, no `Date.now()`: the caller supplies `now` (defaults
+ * to `new Date()` at the call site) so `select()` is a pure, replayable
+ * function of its inputs.
+ */
+
+interface CabarUnit {
+    id: string;
+    content: string;
+    /** Relevance from your retriever, normalized to [0,1] (top item ideally 1.0). */
+    score: number;
+    timestamp?: Date;
+    /** Optional vector for `similarity: embeddingSimilarity`. */
+    embedding?: ArrayLike<number>;
+}
+interface CabarSelectOptions {
+    /** Token budget for the guaranteed block + selected units. The tail summary is capped separately by tailBudgetTokens. */
+    budgetTokens?: number;
+    /** Hard cap on the number of units selected, independent of budget. */
+    maxUnits?: number;
+    /** Hard token cap for the extractive tail summary (on top of budgetTokens). */
+    tailBudgetTokens?: number;
+    /** Minimum relevance score for a unit to survive into the tail at all (below this: dropped). */
+    tauFloor?: number;
+    /**
+     * Blend factor between "ignore recency" (0) and "full recency effect" (1).
+     * ρ = recencyLambda × decay + (1 − recencyLambda). At 0, ρ ≡ 1 for every
+     * unit regardless of timestamp — required for multi-session safety (a
+     * cross-session query shouldn't be penalized just because the recall is old).
+     */
+    recencyLambda?: number;
+    /** Recency scale in days for the exponential decay e^(-age/days). Default 365. */
+    recencyDecayDays?: number;
+    /**
+     * Blend factor between "ignore novelty" (0) and "full novelty effect" (1)
+     * applied to the raw novelty(u,S) ∈ [0,1] term:
+     *   effectiveNovelty = 1 − noveltyWeight × (1 − novelty(u,S))
+     * Defaults to 1, i.e. utility = r × ρ × novelty(u,S) exactly as specified.
+     */
+    noveltyWeight?: number;
+    /** Tokens pre-charged against budgetTokens before selection starts (e.g. the resolved-claims block). */
+    guaranteedTokens?: number;
+    /** Deterministic "current time" for recency scoring. Defaults to `new Date()`. */
+    now?: Date;
+    /**
+     * How hard long units are penalized: greedy density = utility / tokens^costExponent.
+     * 1 (default) = pure value per token, which favors short units. 0.5 softens it so a
+     * long unit that holds the answer can still win; 0 ignores length (pure utility order).
+     */
+    costExponent?: number;
+    /** Also return `decisions`: why each unit was selected, summarized into the tail, or dropped. */
+    explain?: boolean;
+    /** Injectable token cost model. Defaults to the char/4 estimator. */
+    tokenCounter?: TokenCounter;
+    /**
+     * Similarity used for novelty, in [0, 1]. Defaults to word-set Jaccard.
+     * Pass `embeddingSimilarity` (with `embedding` on each unit) to catch paraphrases.
+     */
+    similarity?: Similarity<CabarUnit>;
+    /**
+     * Adaptive stopping mode. When true, the greedy loop's
+     * stop condition is replaced: instead of the fixed `budgetTokens`/`maxUnits`
+     * caps, it keeps accepting units past `minKeep` only while the next unit's
+     * relevance fraction (score / top-candidate score) is >= `relFloor` AND its
+     * novelty vs the already-selected set is >= `novFloor`; `maxCeilingTokens`
+     * becomes the only hard token bound (`maxUnits` is ignored). This lets the
+     * pool's own relevance-score shape decide how much to keep — noisy pools
+     * (one strong hit, many weak ones) stop near `minKeep`; concentrated/spread
+     * pools with a genuine relevant tail keep more. Default false: behavior is
+     * byte-identical to the fixed-budget path.
+     */
+    adaptive?: boolean;
+    /** Adaptive mode: units accepted before the relFloor/novFloor stop rule can trigger. Default 3. */
+    minKeep?: number;
+    /** Adaptive mode: below this fraction of the top candidate's score, the greedy fill stops. Default 0.4. */
+    relFloor?: number;
+    /** Adaptive mode: below this novelty vs the selected set, the greedy fill stops. Default 0.2. */
+    novFloor?: number;
+    /** Adaptive mode: hard token ceiling — replaces budgetTokens as the bound. Default 4000. */
+    maxCeilingTokens?: number;
+    /**
+     * Adaptive mode: also honor `maxUnits` as a hard ceiling ("capped adaptive").
+     * The relFloor/novFloor early-stop can still stop BELOW maxUnits on cliff-y
+     * (noisy) pools — this only prevents adaptive from keeping MORE than maxUnits on
+     * uniformly-relevant (concentrated) pools, where the uncapped rule over-keeps
+     * with no accuracy payoff. Unifies cabar1's ceiling with adaptive's early stop:
+     * concentrated → cap binds (≡ cabar1); noisy → cliff stops early (≡ adaptive).
+     * Default false (preserves the original uncapped adaptive arm byte-identically).
+     */
+    capToMaxUnits?: boolean;
+}
+interface CabarStats {
+    candidateCount: number;
+    candidateTokens: number;
+    selectedTokens: number;
+    tailSummaryTokens: number;
+    budgetTokens: number;
+    /** guaranteedTokens + selectedTokens + tailSummaryTokens — actual spend against budgetTokens. */
+    utilizedTokens: number;
+}
+interface CabarDecision {
+    id: string;
+    status: 'selected' | 'tail' | 'dropped';
+    /** Plain-English reason, e.g. "redundant with u3 (similarity 0.82)". */
+    reason: string;
+    tokens: number;
+    relevance: number;
+    recency: number;
+    /** 1 − highest similarity to any (other) selected unit. */
+    novelty: number;
+    /** For redundant units: the selected unit it overlaps most. */
+    redundantWith?: string;
+}
+interface CabarSelectResult {
+    selected: CabarUnit[];
+    /** Unselected units at or above tauFloor — summarized into tailSummary, not dropped. */
+    tail: CabarUnit[];
+    tailSummary: string;
+    stats: CabarStats;
+    /** Present when `explain: true`, one entry per input unit in input order. */
+    decisions?: CabarDecision[];
+}
+/** Fixed-mode selector defaults. Exported so `cabar.config.ts` can source the
+ * budget/maxUnits ceilings from one place instead of re-declaring the literals. */
+declare const DEFAULTS: Required<Omit<CabarSelectOptions, 'now' | 'tokenCounter' | 'similarity' | 'explain' | 'adaptive' | 'minKeep' | 'relFloor' | 'novFloor' | 'maxCeilingTokens' | 'capToMaxUnits'>>;
+/** Adaptive-mode-only defaults (fixed global constants, never tuned per query type). */
+declare const ADAPTIVE_DEFAULTS: {
+    minKeep: number;
+    relFloor: number;
+    novFloor: number;
+    maxCeilingTokens: number;
+};
+declare class CabarSelector {
+    /**
+     * Select which units fit the budget, greedily maximizing utility/cost
+     * density, with a best-single-vs-greedy swap (budgeted-max-coverage 2-approx
+     * guarantee) and an extractive tail summary for the rest.
+     */
+    static select(units: CabarUnit[], query: string, opts?: CabarSelectOptions): CabarSelectResult;
+}
+
+export { ADAPTIVE_DEFAULTS as A, type CabarSelectResult as C, DEFAULTS as D, type Similarity as S, type TokenCounter as T, type CabarUnit as a, type CabarSelectOptions as b, CHAR4_COUNTER as c, type CabarDecision as d, CabarSelector as e, type CabarStats as f, DEFAULT_RECENCY_DECAY_DAYS as g, cosineSimilarity as h, embeddingSimilarity as i, estimateTokens as j, recencyDecay as r };