@seanhogg/builderforce-memory 2026.7.14 → 2026.9.28

package/src/rag/EnterpriseRetriever.ts

@@ -0,0 +1,348 @@
+/**
+ * rag/EnterpriseRetriever.ts — hybrid, tenant-scoped, cited retrieval.
+ *
+ * The gap between a RAG demo and an enterprise RAG system is not the embedding
+ * model. It is these five properties, all of which live here:
+ *
+ *   1. **Scoped.** Every read carries an {@link AccessScope} that is compiled into
+ *      the database query. There is no code path that reads unscoped, so a
+ *      cross-tenant answer is not something a caller can cause by forgetting.
+ *   2. **Hybrid.** Dense retrieval alone misses exact tokens — error codes, SKUs,
+ *      contract clause numbers, function names. Lexical search alone misses
+ *      paraphrase. RRF over both, then MMR for diversity, then an optional
+ *      reranker.
+ *   3. **Honest about degradation.** When the store has no lexical index the
+ *      retrieval is dense-only and SAYS so on the span and in the result, instead
+ *      of quietly returning worse answers.
+ *   4. **Cited.** Every passage carries its source id, title and URI, and the
+ *      prompt builder numbers them, so an answer can be checked. An uncitable
+ *      answer is an unauditable one, and enterprises audit.
+ *   5. **Traced and costed.** Retrieval and generation are spans under one trace,
+ *      with token counts and cost, so "why was this answer bad" and "why did this
+ *      cost that" are answerable from the same record.
+ */
+
+import type { TransformerBridge } from '../bridges/TransformerBridge.js';
+import { maximalMarginalRelevance, reciprocalRankFusion } from '../retrieval/fusion.js';
+import type { Span, Tracer } from '../telemetry/Tracer.js';
+import {
+    SOURCE_ID_FIELD,
+    TITLE_FIELD,
+    URI_FIELD,
+} from '../ingest/types.js';
+import type {
+    AccessScope,
+    MetadataFilter,
+    VectorMatch,
+    VectorStore,
+} from '../vectorstore/types.js';
+
+/** Reranker port — a cross-encoder, an LLM judge, or a hosted rerank endpoint. */
+export type Reranker = (
+    query: string,
+    passages: readonly RetrievedPassage[],
+) => Promise<readonly RetrievedPassage[]>;
+
+export interface RetrievedPassage {
+    id: string;
+    text: string;
+    /** Fused relevance score. */
+    score: number;
+    sourceId: string;
+    title?: string;
+    uri?: string;
+    metadata: Record<string, unknown>;
+}
+
+export type RetrievalMode = 'hybrid' | 'dense-only' | 'keyword-only' | 'empty';
+
+export interface RetrievalResult {
+    passages: RetrievedPassage[];
+    /** What actually ran — `dense-only` means the store had no lexical index. */
+    mode: RetrievalMode;
+    /** Candidates considered before fusion and truncation. */
+    candidatesConsidered: number;
+    traceId?: string;
+}
+
+export interface RetrieveOptions {
+    /** Tenant/ACL scope. Required unless the retriever was built with a default. */
+    scope?: AccessScope;
+    /** Extra metadata predicate, AND-ed with the scope. */
+    filter?: MetadataFilter;
+    /** Passages returned. Default 5. */
+    topK?: number;
+    /** Candidates pulled from each retrieval arm before fusion. Default `topK * 4`. */
+    candidateK?: number;
+    /** Drop passages below this fused score after normalisation. Default 0. */
+    minScore?: number;
+    /** Parent span, so retrieval nests under the agent turn that asked for it. */
+    parent?: Span;
+}
+
+export interface EnterpriseRetrieverOptions {
+    store: VectorStore;
+    /** Embeds the query. Omit for keyword-only retrieval. */
+    embed?: (text: string) => Promise<Float32Array>;
+    /** Applied to the fused list before truncation. */
+    reranker?: Reranker;
+    /** Default scope, when a deployment is single-tenant or scope comes from context. */
+    defaultScope?: AccessScope;
+    /** RRF weight for the dense arm. Default 1. */
+    denseWeight?: number;
+    /** RRF weight for the lexical arm. Default 1. */
+    keywordWeight?: number;
+    /** MMR relevance/diversity trade-off; 1 is pure relevance. Default 0.7. */
+    mmrLambda?: number;
+    /** Disable the MMR diversity pass. Default false. */
+    disableDiversity?: boolean;
+    tracer?: Tracer;
+}
+
+export class EnterpriseRetriever {
+    private readonly _store: VectorStore;
+    private readonly _embed: ((text: string) => Promise<Float32Array>) | undefined;
+    private readonly _reranker: Reranker | undefined;
+    private readonly _defaultScope: AccessScope | undefined;
+    private readonly _denseWeight: number;
+    private readonly _keywordWeight: number;
+    private readonly _mmrLambda: number;
+    private readonly _diversity: boolean;
+    private readonly _tracer: Tracer | undefined;
+
+    constructor(opts: EnterpriseRetrieverOptions) {
+        this._store = opts.store;
+        this._embed = opts.embed;
+        this._reranker = opts.reranker;
+        this._defaultScope = opts.defaultScope;
+        this._denseWeight = opts.denseWeight ?? 1;
+        this._keywordWeight = opts.keywordWeight ?? 1;
+        this._mmrLambda = opts.mmrLambda ?? 0.7;
+        this._diversity = !opts.disableDiversity;
+        this._tracer = opts.tracer;
+    }
+
+    async retrieve(query: string, opts: RetrieveOptions = {}): Promise<RetrievalResult> {
+        const topK = Math.max(1, opts.topK ?? 5);
+        const candidateK = Math.max(topK, opts.candidateK ?? topK * 4);
+        const scope = opts.scope ?? this._defaultScope;
+
+        const span = this._tracer?.startSpan('retrieval.hybrid', {
+            kind: 'retrieval',
+            ...(opts.parent ? { parent: opts.parent } : {}),
+            attributes: {
+                'retrieval.store': this._store.name,
+                'retrieval.top_k': topK,
+                'retrieval.tenant': scope?.tenantId ?? 'unscoped',
+            },
+        });
+
+        try {
+            const queryVector = this._embed ? await this._embed(query) : undefined;
+
+            const base = {
+                text: query,
+                topK: candidateK,
+                ...(opts.filter ? { filter: opts.filter } : {}),
+                ...(scope ? { scope } : {}),
+                includeVectors: this._diversity,
+            };
+
+            // Both arms run concurrently: they hit different indexes and the
+            // sequential version doubles p95 latency for nothing.
+            const [dense, keyword] = await Promise.all([
+                queryVector
+                    ? this._store.query({ ...base, vector: queryVector })
+                    : Promise.resolve<VectorMatch[]>([]),
+                this._store.keywordSearch
+                    ? this._store.keywordSearch(base)
+                    : Promise.resolve<VectorMatch[]>([]),
+            ]);
+
+            const mode = pickMode(dense.length > 0, keyword.length > 0, Boolean(this._store.keywordSearch));
+            const byId = new Map<string, VectorMatch>();
+            for (const match of [...dense, ...keyword]) {
+                if (!byId.has(match.id)) byId.set(match.id, match);
+            }
+
+            let ordered = this._fuse(dense, keyword, byId);
+
+            if (this._diversity && queryVector && ordered.length > topK) {
+                ordered = this._diversify(queryVector, ordered, byId, topK);
+            }
+
+            let passages = ordered.slice(0, Math.max(topK, this._reranker ? candidateK : topK))
+                .map((hit) => toPassage(byId.get(hit.id) as VectorMatch, hit.score));
+
+            if (this._reranker && passages.length > 0) {
+                passages = [...await this._reranker(query, passages)];
+            }
+            if (opts.minScore !== undefined) {
+                passages = passages.filter((p) => p.score >= (opts.minScore as number));
+            }
+            passages = passages.slice(0, topK);
+
+            span?.setAttributes({
+                'retrieval.mode': mode,
+                'retrieval.candidates': byId.size,
+                'retrieval.returned': passages.length,
+                'retrieval.dense_hits': dense.length,
+                'retrieval.keyword_hits': keyword.length,
+                'retrieval.reranked': Boolean(this._reranker),
+            });
+            span?.end('ok');
+
+            const result: RetrievalResult = {
+                passages,
+                mode,
+                candidatesConsidered: byId.size,
+            };
+            if (span) result.traceId = span.traceId;
+            return result;
+        } catch (err) {
+            span?.fail(err);
+            throw err;
+        }
+    }
+
+    /**
+     * Retrieve, then answer strictly from what was retrieved.
+     *
+     * The system prompt forbids answering beyond the passages and requires
+     * `[n]` citations. That is not decoration: an enterprise deployment is judged
+     * on whether a wrong answer is *detectable*, and an uncited claim is not.
+     */
+    async answer(
+        query: string,
+        bridge: TransformerBridge,
+        opts: RetrieveOptions & { systemPrompt?: string; maxTokens?: number; model?: string } = {},
+    ): Promise<{ answer: string; result: RetrievalResult }> {
+        const span = this._tracer?.startSpan('rag.answer', {
+            kind: 'agent',
+            ...(opts.parent ? { parent: opts.parent } : {}),
+        });
+
+        try {
+            const result = await this.retrieve(query, { ...opts, ...(span ? { parent: span } : {}) });
+
+            if (result.passages.length === 0) {
+                // Refusing beats hallucinating: with no evidence there is nothing to
+                // ground an answer in, and a confident answer here is the exact
+                // failure enterprises cite when a pilot is killed.
+                span?.setAttribute('rag.refused', true);
+                span?.end('ok');
+                return { answer: NO_EVIDENCE_ANSWER, result };
+            }
+
+            const prompt = buildGroundedPrompt(query, result.passages);
+            const answer = await bridge.generate(prompt, {
+                systemPrompt: opts.systemPrompt ?? GROUNDED_SYSTEM_PROMPT,
+                ...(opts.maxTokens !== undefined ? { maxTokens: opts.maxTokens } : {}),
+                ...(opts.model !== undefined ? { model: opts.model } : {}),
+            });
+
+            span?.setAttributes({ 'rag.passages': result.passages.length, 'rag.mode': result.mode });
+            span?.end('ok');
+            return { answer, result };
+        } catch (err) {
+            span?.fail(err);
+            throw err;
+        }
+    }
+
+    private _fuse(
+        dense: readonly VectorMatch[],
+        keyword: readonly VectorMatch[],
+        byId: Map<string, VectorMatch>,
+    ): Array<{ id: string; score: number }> {
+        const lists = [];
+        if (dense.length) lists.push({ ids: dense.map((m) => m.id), weight: this._denseWeight });
+        if (keyword.length) lists.push({ ids: keyword.map((m) => m.id), weight: this._keywordWeight });
+
+        if (lists.length === 0) return [];
+        if (lists.length === 1) {
+            // One arm: keep the store's own similarity rather than replacing it with
+            // an RRF score, which carries no meaning for a single list.
+            const only = dense.length ? dense : keyword;
+            return only.map((m) => ({ id: m.id, score: m.score }));
+        }
+
+        const fused = reciprocalRankFusion(lists);
+        const best = fused[0]?.score ?? 1;
+        // RRF scores live on a tiny arbitrary scale (~1/60); normalising to [0,1]
+        // keeps `minScore` meaning the same thing on one arm or two.
+        return fused
+            .filter((hit) => byId.has(hit.id))
+            .map((hit) => ({ id: hit.id, score: best > 0 ? hit.score / best : 0 }));
+    }
+
+    private _diversify(
+        queryVector: Float32Array,
+        ordered: Array<{ id: string; score: number }>,
+        byId: Map<string, VectorMatch>,
+        topK: number,
+    ): Array<{ id: string; score: number }> {
+        const candidates = ordered
+            .map((hit) => ({ id: hit.id, vector: byId.get(hit.id)?.vector }))
+            .filter((c): c is { id: string; vector: Float32Array } => Boolean(c.vector));
+
+        // Without stored vectors MMR cannot run; keeping the fused order is the
+        // correct degradation, not an error.
+        if (candidates.length < 2) return ordered;
+
+        const scores = new Map(ordered.map((hit) => [hit.id, hit.score]));
+        const picked = maximalMarginalRelevance(queryVector, candidates, topK, this._mmrLambda);
+        const pickedSet = new Set(picked);
+
+        return [
+            ...picked.map((id) => ({ id, score: scores.get(id) ?? 0 })),
+            ...ordered.filter((hit) => !pickedSet.has(hit.id)),
+        ];
+    }
+}
+
+function pickMode(hasDense: boolean, hasKeyword: boolean, storeHasKeyword: boolean): RetrievalMode {
+    if (hasDense && hasKeyword) return 'hybrid';
+    if (hasDense) return 'dense-only';
+    if (hasKeyword) return 'keyword-only';
+    return storeHasKeyword ? 'empty' : 'dense-only';
+}
+
+function toPassage(match: VectorMatch, score: number): RetrievedPassage {
+    const metadata = match.metadata as Record<string, unknown>;
+    const passage: RetrievedPassage = {
+        id: match.id,
+        text: match.text,
+        score,
+        sourceId: String(metadata[SOURCE_ID_FIELD] ?? match.id),
+        metadata,
+    };
+    const title = metadata[TITLE_FIELD];
+    if (typeof title === 'string') passage.title = title;
+    const uri = metadata[URI_FIELD];
+    if (typeof uri === 'string') passage.uri = uri;
+    return passage;
+}
+
+export const GROUNDED_SYSTEM_PROMPT =
+    'You answer strictly from the numbered passages provided. ' +
+    'Cite every claim with the passage number in square brackets, e.g. [2]. ' +
+    'If the passages do not contain the answer, say so plainly and name what is missing. ' +
+    'Never rely on knowledge that is not in the passages.';
+
+export const NO_EVIDENCE_ANSWER =
+    'No indexed passage matched this question within the caller\'s access scope, ' +
+    'so there is nothing to ground an answer in.';
+
+/** Renders passages as a numbered, citable evidence block. */
+export function buildGroundedPrompt(query: string, passages: readonly RetrievedPassage[]): string {
+    const evidence = passages
+        .map((p, i) => {
+            const label = p.title ?? p.sourceId;
+            const uri = p.uri ? ` (${p.uri})` : '';
+            return `[${i + 1}] ${label}${uri}\n${p.text}`;
+        })
+        .join('\n\n');
+
+    return `Passages:\n\n${evidence}\n\nQuestion: ${query}\n\nAnswer, citing passages by number:`;
+}

package/src/rag/index.ts

@@ -0,0 +1,18 @@
+/**
+ * rag — enterprise retrieval: hybrid, tenant/ACL scoped, cited, traced.
+ */
+
+export {
+    EnterpriseRetriever,
+    buildGroundedPrompt,
+    GROUNDED_SYSTEM_PROMPT,
+    NO_EVIDENCE_ANSWER,
+} from './EnterpriseRetriever.js';
+export type {
+    EnterpriseRetrieverOptions,
+    RetrieveOptions,
+    RetrievalResult,
+    RetrievalMode,
+    RetrievedPassage,
+    Reranker,
+} from './EnterpriseRetriever.js';

package/src/retrieval/bm25.ts

@@ -6,16 +6,39 @@
  * Fusing the two (see {@link ./fusion}) is what lifts the memory layer from
  * "cosine only" to a hybrid retriever on par with Weaviate-style search.
  *
- * Pure and zero-dependency — reuses the shared `tokenize` from ../similarity.
+ * Two things are separable here and are kept separate on purpose:
+ *
+ *   • the SCORING CORE ({@link bm25Idf}, {@link bm25LengthNorm}, {@link bm25TermScore})
+ *     — the Okapi formula itself, which is the same wherever lexical relevance is
+ *     scored, whether the index is built inline from raw text or read out of a
+ *     precomputed per-field term table (BM25F). Exported so a consumer with its own
+ *     index shape reuses the maths instead of restating it and drifting from it;
+ *   • the TOKENIZER — which is genuinely corpus-specific. Prose wants stopword
+ *     removal and stemming; identifiers and error codes want neither. So the
+ *     tokenizer is an injectable {@link Bm25Options.tokenize} hook defaulting to the
+ *     package's plain `tokenize`, rather than a second copy of BM25 growing around
+ *     each specialisation.
+ *
+ * Pure and zero-dependency.
  */
 
 import { tokenize } from '../similarity/index.js';
 
+/** Splits text into the terms BM25 scores over. */
+export type Bm25Tokenizer = (text: string) => string[];
+
 export interface Bm25Options {
     /** Term-frequency saturation. Higher = TF matters more. Default 1.5. */
     k1?: number;
     /** Length normalisation, 0..1. Higher = penalise long docs more. Default 0.75. */
     b?: number;
+    /**
+     * Tokenizer for both the query and the documents. Default is the package's plain
+     * `tokenize` (lowercase word split), which preserves identifiers verbatim. Supply
+     * a stemming/stopword tokenizer when the corpus is prose — the SAME function must
+     * be used for query and documents or nothing will match.
+     */
+    tokenize?: Bm25Tokenizer;
 }
 
 export interface Bm25Doc {
@@ -28,6 +51,45 @@ export interface Bm25Hit {
     score: number;
 }
 
+/** Term-frequency saturation used when {@link Bm25Options.k1} is omitted. */
+export const BM25_DEFAULT_K1 = 1.5;
+/** Length normalisation used when {@link Bm25Options.b} is omitted. */
+export const BM25_DEFAULT_B = 0.75;
+
+/**
+ * Inverse document frequency with the +1 smoothing variant, which is always
+ * non-negative — the unsmoothed form goes negative for a term present in more than
+ * half the corpus, which subtracts score for a MATCH.
+ */
+export function bm25Idf(documentCount: number, documentFrequency: number): number {
+    const n = Math.max(documentCount, 1);
+    const df = Math.max(0, Math.min(documentFrequency, n));
+    return Math.log(1 + (n - df + 0.5) / (df + 0.5));
+}
+
+/**
+ * The document-length penalty `1 - b + b·(len/avgdl)`, factored out because it is
+ * per-DOCUMENT: computing it once and reusing it across the query's terms is what
+ * keeps scoring O(terms) rather than O(terms) divisions of the same quotient.
+ */
+export function bm25LengthNorm(length: number, averageLength: number, b: number = BM25_DEFAULT_B): number {
+    const avg = averageLength > 0 ? averageLength : 1;
+    return 1 - b + b * (Math.max(0, length) / avg);
+}
+
+/**
+ * One term's contribution: `idf · f(k1+1) / (f + k1·lengthNorm)`.
+ *
+ * `frequency` is whatever the caller counts as the term's occurrence weight — a raw
+ * count for plain BM25, or a field-weighted sum for BM25F. Combining fields BEFORE
+ * saturation (rather than saturating each field and summing) is what makes BM25F
+ * behave like BM25 over a weighted document.
+ */
+export function bm25TermScore(frequency: number, idf: number, lengthNorm: number, k1: number = BM25_DEFAULT_K1): number {
+    if (frequency <= 0) return 0;
+    return (idf * (frequency * (k1 + 1))) / (frequency + k1 * lengthNorm);
+}
+
 /**
  * Scores every document against `query` with Okapi BM25, returning hits sorted by
  * descending score (documents with no query-term overlap score 0 and are dropped).
@@ -35,12 +97,13 @@ export interface Bm25Hit {
  * store / a vector pre-filter) this is O(N·terms) and needs no persistence.
  */
 export function bm25Search(query: string, docs: Bm25Doc[], opts: Bm25Options = {}): Bm25Hit[] {
-    const k1 = opts.k1 ?? 1.5;
-    const b = opts.b ?? 0.75;
+    const k1 = opts.k1 ?? BM25_DEFAULT_K1;
+    const b = opts.b ?? BM25_DEFAULT_B;
+    const split = opts.tokenize ?? tokenize;
     const N = docs.length;
     if (N === 0) return [];
 
-    const queryTerms = new Set(tokenize(query));
+    const queryTerms = new Set(split(query));
     if (queryTerms.size === 0) return [];
 
     // Per-doc term frequencies + document lengths.
@@ -49,7 +112,7 @@ export function bm25Search(query: string, docs: Bm25Doc[], opts: Bm25Options = {
     let totalLen = 0;
 
     for (const doc of docs) {
-        const tokens = tokenize(doc.text);
+        const tokens = split(doc.text);
         const tf = new Map<string, number>();
         for (const t of tokens) tf.set(t, (tf.get(t) ?? 0) + 1);
         for (const t of tf.keys()) if (queryTerms.has(t)) df.set(t, (df.get(t) ?? 0) + 1);
@@ -58,22 +121,17 @@ export function bm25Search(query: string, docs: Bm25Doc[], opts: Bm25Options = {
     }
     const avgdl = totalLen / N || 1;
 
-    // idf with the +1 smoothing variant (always non-negative).
     const idf = new Map<string, number>();
-    for (const term of queryTerms) {
-        const n = df.get(term) ?? 0;
-        idf.set(term, Math.log(1 + (N - n + 0.5) / (n + 0.5)));
-    }
+    for (const term of queryTerms) idf.set(term, bm25Idf(N, df.get(term) ?? 0));
 
     const hits: Bm25Hit[] = [];
     for (const d of docTerms) {
+        const lengthNorm = bm25LengthNorm(d.len, avgdl, b);
         let score = 0;
         for (const term of queryTerms) {
             const f = d.tf.get(term);
             if (!f) continue;
-            const numer = f * (k1 + 1);
-            const denom = f + k1 * (1 - b + b * (d.len / avgdl));
-            score += idf.get(term)! * (numer / denom);
+            score += bm25TermScore(f, idf.get(term)!, lengthNorm, k1);
         }
         if (score > 0) hits.push({ id: d.id, score });
     }

package/src/retrieval/index.ts

@@ -9,8 +9,8 @@
 export { chunkText } from './chunk.js';
 export type { Chunk, ChunkOptions } from './chunk.js';
 
-export { bm25Search } from './bm25.js';
-export type { Bm25Doc, Bm25Hit, Bm25Options } from './bm25.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';

package/src/telemetry/InstrumentedBridge.ts

@@ -0,0 +1,152 @@
+/**
+ * telemetry/InstrumentedBridge.ts — one decorator that makes ANY bridge observable.
+ *
+ * The alternative — instrumenting Anthropic, OpenAI, Vertex, Fetch, Caching and
+ * SemanticCaching bridges each in their own way — guarantees six subtly different
+ * definitions of "a call". This is a single decorator over the
+ * {@link TransformerBridge} port, so a bridge added tomorrow is observable the
+ * moment it satisfies the interface, and the caching bridges are measured at the
+ * same seam as the provider bridges (which is how the cache-hit rate becomes a
+ * real number rather than an anecdote).
+ *
+ * Token counts come from the provider when the inner bridge reports them via
+ * `lastCall`, and are estimated from characters otherwise — with `estimated: true`
+ * carried through to the metric snapshot so a dashboard never mixes measured and
+ * inferred spend without saying so.
+ */
+
+import type { TransformerBridge, BridgeGenerateOptions } from '../bridges/TransformerBridge.js';
+import { estimateTokens } from './pricing.js';
+import { Tracer, type Span } from './Tracer.js';
+import type { LlmUsage } from './types.js';
+
+export interface InstrumentedBridgeOptions {
+    /** Tracer that receives the spans. */
+    tracer: Tracer;
+    /** Model label used when the inner bridge reports none. Default `'unknown'`. */
+    model?: string;
+    /** Span name. Default `'llm.generate'`. */
+    spanName?: string;
+    /**
+     * Parent span, so a model call nests under the agent/graph node that made it.
+     * A function is accepted for the common case where the parent changes per call.
+     */
+    parent?: Span | (() => Span | undefined);
+    /** Static attributes stamped on every span (tenant, environment, route). */
+    attributes?: Record<string, string | number | boolean>;
+    /**
+     * Token counter, when an exact one is available (e.g. the provider's
+     * count_tokens endpoint). Default: ~4 chars per token.
+     */
+    countTokens?: (text: string) => number;
+}
+
+export class InstrumentedBridge implements TransformerBridge {
+    readonly supportsStreaming: boolean;
+
+    private readonly _inner: TransformerBridge;
+    private readonly _tracer: Tracer;
+    private readonly _model: string;
+    private readonly _spanName: string;
+    private readonly _parent?: Span | (() => Span | undefined);
+    private readonly _attributes: Record<string, string | number | boolean>;
+    private readonly _count: (text: string) => number;
+
+    private _lastCall: { usage?: LlmUsage; cacheHit?: boolean; cacheTier?: string } | undefined;
+
+    constructor(inner: TransformerBridge, opts: InstrumentedBridgeOptions) {
+        this._inner = inner;
+        this._tracer = opts.tracer;
+        this._model = opts.model ?? 'unknown';
+        this._spanName = opts.spanName ?? 'llm.generate';
+        if (opts.parent) this._parent = opts.parent;
+        this._attributes = opts.attributes ?? {};
+        this._count = opts.countTokens ?? estimateTokens;
+        this.supportsStreaming = inner.supportsStreaming;
+    }
+
+    /** Usage/cache info for the most recent call — makes the decorator chainable. */
+    get lastCall(): { usage?: LlmUsage; cacheHit?: boolean; cacheTier?: string } | undefined {
+        return this._lastCall;
+    }
+
+    async generate(prompt: string, opts: BridgeGenerateOptions = {}): Promise<string> {
+        const span = this._startSpan(prompt, opts, false);
+        try {
+            const reply = await this._inner.generate(prompt, opts);
+            this._finish(span, prompt, reply, opts);
+            span.end('ok');
+            return reply;
+        } catch (err) {
+            span.fail(err);
+            throw err;
+        }
+    }
+
+    async *stream(prompt: string, opts: BridgeGenerateOptions = {}): AsyncIterable<string> {
+        if (!this._inner.stream) {
+            throw new Error('InstrumentedBridge: the wrapped bridge does not support streaming.');
+        }
+        const span = this._startSpan(prompt, opts, true);
+        let reply = '';
+        let first = true;
+        try {
+            for await (const chunk of this._inner.stream(prompt, opts)) {
+                if (first) {
+                    span.recordFirstToken();
+                    first = false;
+                }
+                reply += chunk;
+                yield chunk;
+            }
+            this._finish(span, prompt, reply, opts);
+            span.end('ok');
+        } catch (err) {
+            span.fail(err);
+            throw err;
+        }
+    }
+
+    private _startSpan(prompt: string, opts: BridgeGenerateOptions, streaming: boolean): Span {
+        const parent = typeof this._parent === 'function' ? this._parent() : this._parent;
+        const span = this._tracer.startSpan(this._spanName, {
+            kind: 'llm',
+            ...(parent ? { parent } : {}),
+        });
+        span.setAttributes({
+            ...this._attributes,
+            'llm.model': opts.model ?? this._model,
+            'llm.streaming': streaming,
+            'llm.prompt_chars': prompt.length,
+            'llm.max_tokens': opts.maxTokens,
+            'llm.temperature': opts.temperature,
+        });
+        return span;
+    }
+
+    private _finish(span: Span, prompt: string, reply: string, opts: BridgeGenerateOptions): void {
+        const reported = (this._inner as { lastCall?: { usage?: LlmUsage; cacheHit?: boolean; cacheTier?: string } }).lastCall;
+        const model = reported?.usage?.model ?? opts.model ?? this._model;
+
+        const usage: LlmUsage = reported?.usage ?? {
+            model,
+            inputTokens: this._count(prompt),
+            outputTokens: this._count(reply),
+            estimated: true,
+        };
+        if (reported?.cacheHit) usage.localCacheHit = true;
+
+        span.recordUsage(usage);
+        span.setAttributes({
+            'llm.response_chars': reply.length,
+            'llm.cache_hit': reported?.cacheHit ?? false,
+            'llm.cache_tier': reported?.cacheTier,
+        });
+
+        this._lastCall = {
+            usage,
+            ...(reported?.cacheHit !== undefined ? { cacheHit: reported.cacheHit } : {}),
+            ...(reported?.cacheTier !== undefined ? { cacheTier: reported.cacheTier } : {}),
+        };
+    }
+}