@seanhogg/builderforce-memory 2026.9.29 → 2026.9.30

package/src/retrieval/HybridRetriever.ts

@@ -15,7 +15,8 @@
  */
 
 import { bm25Search, type Bm25Options } from './bm25.js';
-import { reciprocalRankFusion, maximalMarginalRelevance, type MmrCandidate } from './fusion.js';
+import { reciprocalRankFusion } from './fusion.js';
+import { maximalMarginalRelevance, type MmrCandidate } from './mmr.js';
 import { denseSearch } from './hnsw.js';
 
 export interface RetrievalCandidate {

package/src/retrieval/decay.ts

@@ -0,0 +1,29 @@
+/**
+ * Recency decay — exponential half-life down-weighting of an older result's score.
+ *
+ * `score · e^(−λ·age)` with `λ = ln2 / halfLife`, so a result `halfLife` days old
+ * keeps half its score. The maths is here; deciding how old a result IS (a dated
+ * file name, an mtime, a `created_at` column) and which results never decay stays
+ * with the caller, because that is a property of its corpus.
+ *
+ * Pure and zero-dependency.
+ */
+
+/** The decay rate for a half-life in days; 0 (no decay) for a non-positive or non-finite half-life. */
+export function toDecayLambda(halfLifeDays: number): number {
+    if (!Number.isFinite(halfLifeDays) || halfLifeDays <= 0) return 0;
+    return Math.LN2 / halfLifeDays;
+}
+
+/** The factor in (0,1] a score is multiplied by at `ageInDays` (negative ages count as 0). */
+export function calculateTemporalDecayMultiplier(params: { ageInDays: number; halfLifeDays: number }): number {
+    const lambda = toDecayLambda(params.halfLifeDays);
+    const clampedAge = Math.max(0, params.ageInDays);
+    if (lambda <= 0 || !Number.isFinite(clampedAge)) return 1;
+    return Math.exp(-lambda * clampedAge);
+}
+
+/** `score` decayed for its age. */
+export function applyTemporalDecayToScore(params: { score: number; ageInDays: number; halfLifeDays: number }): number {
+    return params.score * calculateTemporalDecayMultiplier(params);
+}

package/src/retrieval/fusion.ts

@@ -1,18 +1,13 @@
 /**
- * Rank fusion + diversity reranking.
- *
- *   • Reciprocal Rank Fusion (RRF) merges the dense (vector) and sparse (BM25)
- *     rankings into one list without needing the two score scales to be
- *     commensurable — it fuses on RANK, not raw score. This is the standard,
- *     parameter-light way to combine hybrid retrieval signals.
- *   • Maximal Marginal Relevance (MMR) reranks the fused list to trade off
- *     relevance against novelty, so the top-k isn't five near-duplicate chunks.
+ * Reciprocal Rank Fusion (RRF) — merges rankings (dense vector, sparse BM25, …) into
+ * one list without needing their score scales to be commensurable: it fuses on
+ * RANK, not raw score. The standard, parameter-light way to combine hybrid signals.
+ * Score-based fusion lives in {@link ./weightedFusion}; diversity reranking in
+ * {@link ./mmr}.
  *
  * Pure and zero-dependency.
  */
 
-import { cosineSimilarity } from '../similarity/index.js';
-
 export interface RankedList {
     /** Ordered ids, most relevant first. */
     ids: string[];
@@ -25,60 +20,32 @@ export interface FusedHit {
     score: number;
 }
 
+/** The canonical TREC damping constant for {@link rrfTerm}. */
+export const RRF_DEFAULT_K = 60;
+
+/**
+ * One list's RRF contribution for the item at zero-based `rank`: `1 / (k + rank + 1)`.
+ * Exported for a ranker that blends the rank signal into a score of its own rather
+ * than fusing whole lists.
+ */
+export function rrfTerm(rank: number, k: number = RRF_DEFAULT_K): number {
+    return 1 / (k + rank + 1);
+}
+
 /**
  * Reciprocal Rank Fusion over any number of ranked lists.
  * score(d) = Σ_lists weight / (k + rank(d)).  `k` (default 60) damps the
  * contribution of low-ranked items; the canonical TREC value.
  */
-export function reciprocalRankFusion(lists: RankedList[], k = 60): FusedHit[] {
+export function reciprocalRankFusion(lists: RankedList[], k = RRF_DEFAULT_K): FusedHit[] {
     const acc = new Map<string, number>();
     for (const list of lists) {
         const weight = list.weight ?? 1;
         list.ids.forEach((id, rank) => {
-            acc.set(id, (acc.get(id) ?? 0) + weight / (k + rank + 1));
+            acc.set(id, (acc.get(id) ?? 0) + weight * rrfTerm(rank, k));
         });
     }
     return [...acc.entries()]
         .map(([id, score]) => ({ id, score }))
         .sort((a, b) => b.score - a.score);
 }
-
-export interface MmrCandidate {
-    id: string;
-    vector: Float32Array;
-}
-
-/**
- * Maximal Marginal Relevance rerank. Greedily selects up to `topK` candidates,
- * each step maximising `λ·sim(query, d) − (1−λ)·max sim(d, already-selected)`.
- * λ=1 is pure relevance; lower λ injects diversity. Candidates without vectors
- * should be filtered out by the caller (they cannot be MMR-scored).
- */
-export function maximalMarginalRelevance(
-    queryVec: Float32Array,
-    candidates: MmrCandidate[],
-    topK: number,
-    lambda = 0.7,
-): string[] {
-    const remaining = [...candidates];
-    const selected: MmrCandidate[] = [];
-    const relevance = new Map<string, number>();
-    for (const c of remaining) relevance.set(c.id, cosineSimilarity(queryVec, c.vector));
-
-    while (selected.length < topK && remaining.length > 0) {
-        let bestIdx = 0;
-        let bestScore = -Infinity;
-        for (let i = 0; i < remaining.length; i++) {
-            const c = remaining[i]!;
-            let maxSimToSelected = 0;
-            for (const s of selected) {
-                const sim = cosineSimilarity(c.vector, s.vector);
-                if (sim > maxSimToSelected) maxSimToSelected = sim;
-            }
-            const mmr = lambda * relevance.get(c.id)! - (1 - lambda) * maxSimToSelected;
-            if (mmr > bestScore) { bestScore = mmr; bestIdx = i; }
-        }
-        selected.push(remaining.splice(bestIdx, 1)[0]!);
-    }
-    return selected.map(s => s.id);
-}

package/src/retrieval/index.ts

@@ -1,19 +1,37 @@
 /**
- * Retrieval layer — chunking, BM25, rank fusion, and the HybridRetriever.
+ * Retrieval layer — chunking, BM25, rank and score fusion, MMR, recency decay, the
+ * similarity primitives they rest on, and the HybridRetriever.
  *
- * The classic RAG pieces the memory stack previously lacked (chunking, hybrid
- * dense+sparse search, reranking), implemented zero-dependency so they run in the
- * browser, Node, and the SSM runtime alike.
+ * Zero-dependency and engine-free: this is the `@seanhogg/builderforce-memory/retrieval`
+ * subpath, which a Cloudflare Worker, Node and the browser can all import without
+ * pulling the WebGPU engine. Every host ranks with THESE functions rather than a copy.
  */
 
+export { cosineSimilarity, jaccardSimilarity, tokenize } from '../similarity/index.js';
+
 export { chunkText } from './chunk.js';
 export type { Chunk, ChunkOptions } from './chunk.js';
 
 export { bm25Search, bm25Idf, bm25LengthNorm, bm25TermScore, BM25_DEFAULT_K1, BM25_DEFAULT_B } from './bm25.js';
 export type { Bm25Doc, Bm25Hit, Bm25Options, Bm25Tokenizer } from './bm25.js';
 
-export { reciprocalRankFusion, maximalMarginalRelevance } from './fusion.js';
-export type { RankedList, FusedHit, MmrCandidate } from './fusion.js';
+export { reciprocalRankFusion, rrfTerm, RRF_DEFAULT_K } from './fusion.js';
+export type { RankedList, FusedHit } from './fusion.js';
+
+export { mmrSelect, maximalMarginalRelevance, textMaximalMarginalRelevance } from './mmr.js';
+export type { MmrSelectOptions, MmrCandidate, TextMmrItem } from './mmr.js';
+
+export {
+    DEFAULT_HYBRID_VECTOR_WEIGHT,
+    DEFAULT_HYBRID_TEXT_WEIGHT,
+    normalizeHybridWeights,
+    hybridScore,
+    bm25RankToScore,
+    fuseHybridArms,
+} from './weightedFusion.js';
+export type { HybridWeights, HybridArmScores } from './weightedFusion.js';
+
+export { toDecayLambda, calculateTemporalDecayMultiplier, applyTemporalDecayToScore } from './decay.js';
 
 export { hybridRetrieve } from './HybridRetriever.js';
 export type {

package/src/retrieval/mmr.ts

@@ -0,0 +1,126 @@
+/**
+ * Maximal Marginal Relevance — ONE greedy selection loop, two similarity bases.
+ *
+ * MMR reranks a relevance-ordered list so the top of it is not five near-duplicates:
+ * each step picks the candidate maximising `λ·relevance − (1−λ)·max sim(candidate,
+ * already-selected)`. λ=1 is pure relevance; lower λ buys diversity.
+ *
+ * What differs between callers is only what "similar" means:
+ *   • {@link maximalMarginalRelevance} — cosine over embedding vectors, relevance =
+ *     cosine to the query vector. For retrievers that hold vectors;
+ *   • {@link textMaximalMarginalRelevance} — Jaccard over word tokens, relevance =
+ *     the candidate's own score min-max normalised onto [0,1]. For retrievers that
+ *     only have text and a fused score (an FTS5 + sqlite-vec hybrid, say).
+ *
+ * Both run {@link mmrSelect}, so the selection rule itself exists once.
+ *
+ * Pure and zero-dependency.
+ */
+
+import { cosineSimilarity, jaccardSimilarity, tokenize } from '../similarity/index.js';
+
+export interface MmrSelectOptions<T> {
+    /** Relevance of one candidate, on the same scale as {@link similarity}. */
+    relevance: (item: T) => number;
+    /** Similarity of two candidates. */
+    similarity: (a: T, b: T) => number;
+    /** 0 = maximum diversity, 1 = maximum relevance. Default 0.7. */
+    lambda?: number;
+    /** Stop after this many picks. Default: every candidate. */
+    topK?: number;
+    /**
+     * Breaks an exact MMR tie in favour of the higher value. Without it the earlier
+     * candidate wins, so input order decides.
+     */
+    tieScore?: (item: T) => number;
+}
+
+/** Greedy MMR selection. Returns the picked candidates in pick order. */
+export function mmrSelect<T>(items: readonly T[], opts: MmrSelectOptions<T>): T[] {
+    const lambda = opts.lambda ?? 0.7;
+    const limit = Math.min(opts.topK ?? items.length, items.length);
+    const remaining = [...items];
+    const relevance = new Map<T, number>();
+    for (const item of remaining) relevance.set(item, opts.relevance(item));
+
+    const selected: T[] = [];
+    while (selected.length < limit && remaining.length > 0) {
+        let bestIdx = -1;
+        let bestScore = -Infinity;
+        for (let i = 0; i < remaining.length; i++) {
+            const candidate = remaining[i]!;
+            let maxSimToSelected = 0;
+            for (const s of selected) {
+                const sim = opts.similarity(candidate, s);
+                if (sim > maxSimToSelected) maxSimToSelected = sim;
+            }
+            const score = lambda * relevance.get(candidate)! - (1 - lambda) * maxSimToSelected;
+            const wins = score > bestScore
+                || (score === bestScore && bestIdx >= 0 && opts.tieScore !== undefined
+                    && opts.tieScore(candidate) > opts.tieScore(remaining[bestIdx]!));
+            if (wins) { bestScore = score; bestIdx = i; }
+        }
+        if (bestIdx < 0) break;
+        selected.push(remaining.splice(bestIdx, 1)[0]!);
+    }
+    return selected;
+}
+
+export interface MmrCandidate {
+    id: string;
+    vector: Float32Array;
+}
+
+/**
+ * Vector MMR. Selects up to `topK` candidates by cosine relevance to `queryVec`,
+ * penalising cosine similarity to what is already selected. Candidates without
+ * vectors should be filtered out by the caller (they cannot be MMR-scored).
+ */
+export function maximalMarginalRelevance(
+    queryVec: Float32Array,
+    candidates: MmrCandidate[],
+    topK: number,
+    lambda = 0.7,
+): string[] {
+    return mmrSelect(candidates, {
+        relevance: (c) => cosineSimilarity(queryVec, c.vector),
+        similarity: (a, b) => cosineSimilarity(a.vector, b.vector),
+        lambda,
+        topK,
+    }).map((c) => c.id);
+}
+
+export interface TextMmrItem {
+    id: string;
+    /** The candidate's fused relevance score (any scale — it is normalised here). */
+    score: number;
+    /** The text diversity is judged on. */
+    content: string;
+}
+
+/**
+ * Text MMR. Reorders every item, judging diversity by Jaccard similarity of word
+ * tokens, and relevance by the item's `score` min-max normalised onto [0,1] (all
+ * equal → 1). An exact tie goes to the higher raw score. `lambda` is clamped to
+ * [0,1]; at 1 this is a plain score sort.
+ */
+export function textMaximalMarginalRelevance<T extends TextMmrItem>(items: readonly T[], lambda = 0.7): T[] {
+    if (items.length <= 1) return [...items];
+    const l = Math.max(0, Math.min(1, lambda));
+    if (l === 1) return [...items].sort((a, b) => b.score - a.score);
+
+    const tokens = new Map<string, Set<string>>();
+    for (const item of items) tokens.set(item.id, new Set(tokenize(item.content)));
+    const tokensOf = (item: T) => tokens.get(item.id) ?? new Set(tokenize(item.content));
+
+    const scores = items.map((i) => i.score);
+    const min = Math.min(...scores);
+    const range = Math.max(...scores) - min;
+
+    return mmrSelect(items, {
+        relevance: (item) => (range === 0 ? 1 : (item.score - min) / range),
+        similarity: (a, b) => jaccardSimilarity(tokensOf(a), tokensOf(b)),
+        lambda: l,
+        tieScore: (item) => item.score,
+    });
+}

package/src/retrieval/weightedFusion.ts

@@ -0,0 +1,101 @@
+/**
+ * Weighted-score fusion — the ONE formula for fusing a semantic arm with a lexical
+ * arm by SCORE, where {@link ./fusion reciprocalRankFusion} fuses by RANK.
+ *
+ * Score fusion is the choice when two different engines must rank the same way: an
+ * on-prem `sqlite-vec` cosine + FTS5/BM25 pair and a cloud pgvector cosine + ILIKE
+ * pair answer the same question, and a weighted sum of scores already on roughly
+ * [0,1] makes "recall ranks the same everywhere" a property of one function.
+ *
+ * Union semantics: a candidate found by only one arm scores 0 on the other rather
+ * than being dropped, because "the lexical arm did not match" is evidence about the
+ * query's wording, not about the candidate's relevance.
+ *
+ * Pure and zero-dependency.
+ */
+
+/** Weight on the semantic arm when a caller states none. */
+export const DEFAULT_HYBRID_VECTOR_WEIGHT = 0.7;
+/** Weight on the lexical arm when a caller states none. */
+export const DEFAULT_HYBRID_TEXT_WEIGHT = 0.3;
+
+export interface HybridWeights {
+    vectorWeight: number;
+    textWeight: number;
+}
+
+/**
+ * Renormalise a pair of weights so it sums to 1 — a fused score is only comparable
+ * across queries if the weights always sum the same. A degenerate pair (both zero
+ * or non-finite) falls back to the defaults.
+ *
+ * The pair is a RATIO, so only the lower bound is clamped: `(3, 1)` means "three
+ * parts semantic to one part lexical" and must come back as 0.75/0.25, not be
+ * capped into an even split. Normalisation is what bounds the result.
+ */
+export function normalizeHybridWeights(vectorWeight?: number, textWeight?: number): HybridWeights {
+    const clamp = (n: number | undefined, fallback: number): number =>
+        typeof n === 'number' && Number.isFinite(n) ? Math.max(0, n) : fallback;
+    const v = clamp(vectorWeight, DEFAULT_HYBRID_VECTOR_WEIGHT);
+    const t = clamp(textWeight, DEFAULT_HYBRID_TEXT_WEIGHT);
+    const sum = v + t;
+    if (sum <= 0) {
+        return { vectorWeight: DEFAULT_HYBRID_VECTOR_WEIGHT, textWeight: DEFAULT_HYBRID_TEXT_WEIGHT };
+    }
+    return { vectorWeight: v / sum, textWeight: t / sum };
+}
+
+/** One candidate's per-arm scores, both already normalised to roughly [0,1]. */
+export interface HybridArmScores {
+    vectorScore?: number;
+    textScore?: number;
+}
+
+/** The fused score for one candidate under the given (already normalised) weights. */
+export function hybridScore(scores: HybridArmScores, weights: HybridWeights): number {
+    const v = Number.isFinite(scores.vectorScore) ? (scores.vectorScore as number) : 0;
+    const t = Number.isFinite(scores.textScore) ? (scores.textScore as number) : 0;
+    return weights.vectorWeight * v + weights.textWeight * t;
+}
+
+/**
+ * Map a BM25 rank (lower is better, unbounded — FTS5's `bm25()`) onto a (0,1]
+ * score so it can be summed with a cosine similarity. A non-finite rank is treated
+ * as very poor rather than as an error.
+ */
+export function bm25RankToScore(rank: number): number {
+    const normalized = Number.isFinite(rank) ? Math.max(0, rank) : 999;
+    return 1 / (1 + normalized);
+}
+
+/**
+ * Fuse two arms keyed by a caller-supplied id and return the candidates ordered
+ * best-first. `merge` builds the output row from the winning payload of each id;
+ * later duplicates of the same id keep the first payload seen (arm order decides).
+ */
+export function fuseHybridArms<TVector extends { id: string }, TText extends { id: string }, TOut>(params: {
+    vector: readonly TVector[];
+    text: readonly TText[];
+    vectorScoreOf: (row: TVector) => number;
+    textScoreOf: (row: TText) => number;
+    merge: (row: TVector | TText, score: number) => TOut;
+    weights?: Partial<HybridWeights>;
+}): TOut[] {
+    const weights = normalizeHybridWeights(params.weights?.vectorWeight, params.weights?.textWeight);
+    const byId = new Map<string, { row: TVector | TText; scores: HybridArmScores }>();
+    for (const row of params.vector) {
+        byId.set(row.id, { row, scores: { vectorScore: params.vectorScoreOf(row), textScore: 0 } });
+    }
+    for (const row of params.text) {
+        const existing = byId.get(row.id);
+        if (existing) existing.scores.textScore = params.textScoreOf(row);
+        else byId.set(row.id, { row, scores: { vectorScore: 0, textScore: params.textScoreOf(row) } });
+    }
+    return [...byId.values()]
+        .map((entry) => {
+            const score = hybridScore(entry.scores, weights);
+            return { out: params.merge(entry.row, score), score };
+        })
+        .sort((a, b) => b.score - a.score)
+        .map((entry) => entry.out);
+}

package/src/similarity/index.ts

@@ -24,12 +24,14 @@ export function jaccardSimilarity(a: Set<string>, b: Set<string>): number {
 }
 
 /**
- * Cosine similarity between two vectors in the range [-1, 1] (0 when either is a
- * zero vector). Compares over the shorter length when lengths differ. Vectors
+ * Cosine similarity between two vectors in the range [-1, 1] (0 when either is empty
+ * or a zero vector). Compares over the shorter length when lengths differ. Vectors
  * from MambaSession.embed() are already L2-normalised — this reduces to a dot
- * product — but we normalise defensively for vectors from other sources.
+ * product — but we normalise defensively for vectors from other sources. Takes any
+ * numeric array, so a `Float32Array` embedding and a JSON-decoded `number[]` (a
+ * pgvector row, a KV entry) go through the same function.
  */
-export function cosineSimilarity(a: Float32Array, b: Float32Array): number {
+export function cosineSimilarity(a: ArrayLike<number>, b: ArrayLike<number>): number {
     const n = Math.min(a.length, b.length);
     let dot = 0, na = 0, nb = 0;
     for (let i = 0; i < n; i++) {

package/src/wire/index.ts

@@ -0,0 +1,18 @@
+/**
+ * LLM wire primitives — the protocol-level pieces every client of an
+ * OpenAI/Anthropic/Gemini-style HTTP API needs, in ONE place:
+ *
+ *   • Server-Sent-Events `data:` framing — one line rule ({@link parseSseDataLine}),
+ *     applied to a whole buffered body ({@link parseSseDataFrames}) or to a live
+ *     byte stream ({@link readSseDataFrames});
+ *   • token-usage field reading across vendor shapes ({@link readUsageFields}) and
+ *     the Anthropic streaming usage fold ({@link AnthropicStreamUsage}).
+ *
+ * The package's bridges and the Builderforce gateway both frame and meter with
+ * these, so a fix to the line rule (a spaceless `data:{…}` frame, say) lands once.
+ * Zero-dependency and engine-free: the `@seanhogg/builderforce-memory/wire` subpath.
+ */
+
+export { parseSseDataLine, parseSseDataFrames, readSseDataFrames, isSseDoneLine } from './sse.js';
+export { finiteNumber, readUsageFields, AnthropicStreamUsage } from './usage.js';
+export type { UsageFields, AnthropicUsageTotals } from './usage.js';

package/src/wire/sse.ts

@@ -0,0 +1,74 @@
+/**
+ * Server-Sent-Events `data:` framing.
+ *
+ * Every consumer of an SSE LLM stream does the same line-level dance: trim the line,
+ * keep only `data:` frames, skip empty payloads, `JSON.parse` the rest and skip
+ * anything malformed — and stop at the `[DONE]` sentinel, which ends an
+ * OpenAI-style stream (anything after it is not part of the response).
+ *
+ * The line rule is `slice(5).trim()`, which accepts both `data: {…}` and the
+ * spaceless `data:{…}` some providers emit — `slice(6)` silently drops the latter.
+ *
+ * Pure and defensive: a malformed frame is skipped, never thrown.
+ */
+
+/**
+ * One SSE line's decoded JSON payload, or `undefined` when the line is not a usable
+ * data frame (not a `data:` line, the `[DONE]` sentinel, empty, or malformed JSON).
+ */
+export function parseSseDataLine(line: string): unknown | undefined {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('data:')) return undefined;
+    const data = trimmed.slice(5).trim();
+    if (!data || data === '[DONE]') return undefined;
+    try {
+        return JSON.parse(data);
+    } catch {
+        return undefined;
+    }
+}
+
+/** True for the `data: [DONE]` line that ends an OpenAI-style stream. */
+export function isSseDoneLine(line: string): boolean {
+    const trimmed = line.trim();
+    return trimmed.startsWith('data:') && trimmed.slice(5).trim() === '[DONE]';
+}
+
+/** Every parsed `data:` frame of a whole, already-buffered SSE body, up to `[DONE]`. */
+export function* parseSseDataFrames(raw: string): Generator<unknown> {
+    for (const line of raw.split('\n')) {
+        if (isSseDoneLine(line)) return;
+        const parsed = parseSseDataLine(line);
+        if (parsed !== undefined) yield parsed;
+    }
+}
+
+/**
+ * Every parsed `data:` frame of a live SSE byte stream, as it arrives, up to `[DONE]`.
+ * A frame split across chunks is held until its line completes; the reader lock is
+ * released however iteration ends.
+ */
+export async function* readSseDataFrames(body: ReadableStream<Uint8Array>): AsyncGenerator<unknown> {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split('\n');
+            buffer = lines.pop() as string; // split() always yields ≥1 element
+            for (const line of lines) {
+                if (isSseDoneLine(line)) return;
+                const parsed = parseSseDataLine(line);
+                if (parsed !== undefined) yield parsed;
+            }
+        }
+        buffer += decoder.decode();
+        const tail = parseSseDataLine(buffer);
+        if (tail !== undefined) yield tail;
+    } finally {
+        reader.releaseLock();
+    }
+}

package/src/wire/usage.ts

@@ -0,0 +1,95 @@
+/**
+ * Token-usage reading across vendor shapes.
+ *
+ * Two wire shapes reach a client: OpenAI-style `prompt_tokens`/`completion_tokens`
+ * (cached reads under `prompt_tokens_details.cached_tokens`, INCLUDED in
+ * `prompt_tokens`) and Anthropic-style `input_tokens`/`output_tokens` (cache reads
+ * and writes as separate top-level fields, EXCLUDED from `input_tokens`).
+ * {@link readUsageFields} reads either into one set of optional fields, keeping
+ * "absent" distinct from 0; each consumer then maps them to its own accounting.
+ *
+ * Streaming Anthropic responses split usage across events — input and cache on
+ * `message_start.message.usage`, output accumulating on `message_delta.usage` — and
+ * every count is cumulative, so {@link AnthropicStreamUsage} keeps the largest seen.
+ */
+
+/** A finite number, or `undefined` for null/undefined/non-numeric input. */
+export function finiteNumber(v: unknown): number | undefined {
+    if (v === null || v === undefined) return undefined;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : undefined;
+}
+
+/** Usage as the vendor reported it. Every field is absent when the vendor omitted it. */
+export interface UsageFields {
+    /** `prompt_tokens`, else `input_tokens`. */
+    promptTokens?: number;
+    /** `completion_tokens`, else `output_tokens`. */
+    completionTokens?: number;
+    totalTokens?: number;
+    /** `cache_read_input_tokens`, else `prompt_tokens_details.cached_tokens`. */
+    cacheReadTokens?: number;
+    /** `cache_creation_input_tokens`. */
+    cacheCreationTokens?: number;
+}
+
+/** Reads a vendor `usage` object of either shape. Anything that is not an object reads as empty. */
+export function readUsageFields(u: unknown): UsageFields {
+    const out: UsageFields = {};
+    if (!u || typeof u !== 'object') return out;
+    const usage = u as Record<string, unknown>;
+    const prompt = finiteNumber(usage['prompt_tokens'] ?? usage['input_tokens']);
+    const completion = finiteNumber(usage['completion_tokens'] ?? usage['output_tokens']);
+    const total = finiteNumber(usage['total_tokens']);
+    if (prompt !== undefined) out.promptTokens = prompt;
+    if (completion !== undefined) out.completionTokens = completion;
+    if (total !== undefined) out.totalTokens = total;
+
+    const details = usage['prompt_tokens_details'];
+    const cachedFromDetails = details && typeof details === 'object'
+        ? finiteNumber((details as Record<string, unknown>)['cached_tokens'])
+        : undefined;
+    const cacheRead = finiteNumber(usage['cache_read_input_tokens']) ?? cachedFromDetails;
+    const cacheCreation = finiteNumber(usage['cache_creation_input_tokens']);
+    if (cacheRead !== undefined) out.cacheReadTokens = cacheRead;
+    if (cacheCreation !== undefined) out.cacheCreationTokens = cacheCreation;
+    return out;
+}
+
+/** The totals of one Anthropic stream. Input excludes both cache counts. */
+export interface AnthropicUsageTotals {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    /** `message_start.message.model`, when the stream named it. */
+    model?: string;
+}
+
+/** Folds the usage events of one Anthropic Messages stream. Feed it every parsed frame. */
+export class AnthropicStreamUsage {
+    private readonly totals: AnthropicUsageTotals = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 };
+
+    observe(frame: unknown): void {
+        if (!frame || typeof frame !== 'object') return;
+        const ev = frame as { type?: unknown; message?: { usage?: unknown; model?: unknown }; usage?: unknown };
+        let usage: unknown;
+        if (ev.type === 'message_start') {
+            usage = ev.message?.usage;
+            if (typeof ev.message?.model === 'string') this.totals.model = ev.message.model;
+        } else if (ev.type === 'message_delta') {
+            usage = ev.usage;
+        }
+        if (!usage || typeof usage !== 'object') return;
+        const u = usage as Record<string, unknown>;
+        const keep = (current: number, v: unknown) => Math.max(current, finiteNumber(v) ?? 0);
+        this.totals.inputTokens = keep(this.totals.inputTokens, u['input_tokens']);
+        this.totals.outputTokens = keep(this.totals.outputTokens, u['output_tokens']);
+        this.totals.cacheReadTokens = keep(this.totals.cacheReadTokens, u['cache_read_input_tokens']);
+        this.totals.cacheCreationTokens = keep(this.totals.cacheCreationTokens, u['cache_creation_input_tokens']);
+    }
+
+    result(): AnthropicUsageTotals {
+        return { ...this.totals };
+    }
+}