@seanhogg/builderforce-memory 2026.6.18

package/src/bridges/OpenAIBridge.ts

@@ -0,0 +1,143 @@
+/**
+ * OpenAIBridge – TransformerBridge implementation for the OpenAI Chat API.
+ *
+ * Supports both non-streaming and streaming (SSE) completions.
+ * Compatible with any OpenAI-compatible endpoint via the `baseUrl` option.
+ */
+
+import { SSMError } from '../errors/SSMError.js';
+import type { TransformerBridge, BridgeGenerateOptions } from './TransformerBridge.js';
+
+export interface OpenAIBridgeOptions {
+    /** OpenAI API key (or compatible service key). */
+    apiKey        : string;
+    /** Model to use. Default: 'gpt-4o-mini'. */
+    model?        : string;
+    /** API base URL. Default: 'https://api.openai.com/v1'. */
+    baseUrl?      : string;
+    /** Default system prompt sent with every request. */
+    systemPrompt? : string;
+    /** Default max tokens. Default: 512. */
+    maxTokens?    : number;
+}
+
+export class OpenAIBridge implements TransformerBridge {
+    readonly supportsStreaming = true as const;
+
+    private readonly _apiKey      : string;
+    private readonly _model       : string;
+    private readonly _baseUrl     : string;
+    private readonly _systemPrompt: string;
+    private readonly _maxTokens   : number;
+
+    constructor(opts: OpenAIBridgeOptions) {
+        this._apiKey       = opts.apiKey;
+        this._model        = opts.model        ?? 'gpt-4o-mini';
+        this._baseUrl      = (opts.baseUrl     ?? 'https://api.openai.com/v1').replace(/\/$/, '');
+        this._systemPrompt = opts.systemPrompt ?? '';
+        this._maxTokens    = opts.maxTokens    ?? 512;
+    }
+
+    async generate(prompt: string, opts: BridgeGenerateOptions = {}): Promise<string> {
+        const body = this._buildBody(prompt, opts, false);
+        const res  = await this._fetch(body);
+
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new SSMError(
+                'BRIDGE_REQUEST_FAILED',
+                `OpenAI API returned ${res.status}: ${text}`,
+            );
+        }
+
+        const json = await res.json() as Record<string, unknown>;
+        const content = (json as any).choices?.[0]?.message?.content;
+        if (typeof content !== 'string') {
+            throw new SSMError('BRIDGE_RESPONSE_INVALID', 'Unexpected OpenAI response shape.');
+        }
+        return content;
+    }
+
+    async *stream(prompt: string, opts: BridgeGenerateOptions = {}): AsyncIterable<string> {
+        const body = this._buildBody(prompt, opts, true);
+        const res  = await this._fetch(body);
+
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new SSMError(
+                'BRIDGE_REQUEST_FAILED',
+                `OpenAI streaming API returned ${res.status}: ${text}`,
+            );
+        }
+
+        if (!res.body) {
+            throw new SSMError('BRIDGE_RESPONSE_INVALID', 'OpenAI streaming response has no body.');
+        }
+
+        yield* parseOpenAIStream(res.body);
+    }
+
+    private _buildBody(prompt: string, opts: BridgeGenerateOptions, stream: boolean): string {
+        const sys = opts.systemPrompt ?? this._systemPrompt;
+        const messages: { role: string; content: string }[] = [];
+        if (sys) messages.push({ role: 'system', content: sys });
+        messages.push({ role: 'user', content: prompt });
+
+        return JSON.stringify({
+            model      : opts.model     ?? this._model,
+            messages,
+            max_tokens : opts.maxTokens ?? this._maxTokens,
+            temperature: opts.temperature ?? 0.7,
+            top_p      : opts.topP        ?? 0.9,
+            stream,
+        });
+    }
+
+    private _fetch(body: string): Promise<Response> {
+        return fetch(`${this._baseUrl}/chat/completions`, {
+            method : 'POST',
+            headers: {
+                'Content-Type' : 'application/json',
+                'Authorization': `Bearer ${this._apiKey}`,
+            },
+            body,
+        });
+    }
+}
+
+// ── SSE parser ────────────────────────────────────────────────────────────────
+
+async function* parseOpenAIStream(body: ReadableStream<Uint8Array>): AsyncIterable<string> {
+    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;   // keep the last (possibly partial) line; split() always yields ≥1 element
+
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed.startsWith('data: ')) continue;
+
+                const data = trimmed.slice(6);
+                if (data === '[DONE]') return;
+
+                try {
+                    const chunk = JSON.parse(data) as Record<string, unknown>;
+                    const delta = (chunk as any).choices?.[0]?.delta?.content;
+                    if (typeof delta === 'string' && delta.length > 0) yield delta;
+                } catch {
+                    // Malformed JSON in stream — skip silently
+                }
+            }
+        }
+    } finally {
+        reader.releaseLock();
+    }
+}

package/src/bridges/ResponseCache.ts

@@ -0,0 +1,131 @@
+/**
+ * ResponseCache – a small, dependency-free read-through cache for transformer
+ * bridge completions.
+ *
+ * This is the canonical cache for this library: a single bounded LRU with an
+ * optional TTL, not an ad-hoc Map inlined at a call site. It exists because an
+ * external LLM call is the most expensive thing the runtime does — identical
+ * (model, system, prompt, sampling) requests should never be billed twice.
+ *
+ * Scope is in-process by design: this package targets the browser and Node, so
+ * there is no shared KV / cross-isolate tier to propagate to (unlike the
+ * BuilderForce.ai gateway, whose read-through cache is L1 Map + L2 KV). A
+ * consumer that needs cross-process sharing can wrap a bridge with its own
+ * distributed cache using the same `CachingBridge` shape.
+ */
+
+export interface ResponseCacheOptions {
+    /**
+     * Maximum number of entries retained. Oldest-accessed entries are evicted
+     * first once the bound is reached. Default: 500.
+     */
+    maxEntries? : number;
+    /**
+     * Optional time-to-live in milliseconds. Entries older than this are treated
+     * as misses and dropped on access. Omit for no expiry (cache until evicted).
+     */
+    ttlMs?      : number;
+}
+
+interface CacheRecord {
+    value     : string;
+    timestamp : number;
+}
+
+const DEFAULT_MAX_ENTRIES = 500;
+
+export class ResponseCache {
+    private readonly _maxEntries : number;
+    private readonly _ttlMs      : number | undefined;
+    // Map preserves insertion order; re-insertion on hit gives us LRU ordering.
+    private readonly _store = new Map<string, CacheRecord>();
+
+    private _hits   = 0;
+    private _misses = 0;
+
+    constructor(opts: ResponseCacheOptions = {}) {
+        this._maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        this._ttlMs      = opts.ttlMs;
+    }
+
+    /**
+     * Returns the cached value for `key`, or `undefined` on a miss (including an
+     * expired entry, which is also evicted). A hit refreshes recency.
+     */
+    get(key: string): string | undefined {
+        const record = this._store.get(key);
+        if (!record) {
+            this._misses++;
+            return undefined;
+        }
+        if (this._isExpired(record)) {
+            this._store.delete(key);
+            this._misses++;
+            return undefined;
+        }
+        // Refresh recency: delete + re-insert moves the key to the newest slot.
+        this._store.delete(key);
+        this._store.set(key, record);
+        this._hits++;
+        return record.value;
+    }
+
+    /** Stores `value` under `key`, evicting the least-recently-used entry if full. */
+    set(key: string, value: string, now: number): void {
+        if (this._store.has(key)) this._store.delete(key);
+        this._store.set(key, { value, timestamp: now });
+
+        while (this._store.size > this._maxEntries) {
+            // size > maxEntries (≥ 0) guarantees the map is non-empty, so the
+            // oldest key always exists — the non-null assertion is safe.
+            const oldest = this._store.keys().next().value as string;
+            this._store.delete(oldest);
+        }
+    }
+
+    /** Drops all cached entries. */
+    clear(): void {
+        this._store.clear();
+    }
+
+    /** Current entry count (including not-yet-evicted expired entries). */
+    get size(): number {
+        return this._store.size;
+    }
+
+    /** Cumulative hit / miss counters, for observability and cache-tuning. */
+    get stats(): { hits: number; misses: number } {
+        return { hits: this._hits, misses: this._misses };
+    }
+
+    private _isExpired(record: CacheRecord): boolean {
+        if (this._ttlMs == null) return false;
+        // `now` is read at access time so a single import of Date is enough; the
+        // caller-supplied `now` on set() keeps insertion timestamps consistent.
+        return Date.now() > record.timestamp + this._ttlMs;
+    }
+}
+
+/**
+ * Builds a stable, collision-resistant cache key from the request shape. Any
+ * field that changes the model's output must be part of the key.
+ */
+export function buildCacheKey(parts: {
+    prompt       : string;
+    model?       : string;
+    systemPrompt? : string;
+    maxTokens?   : number;
+    temperature? : number;
+    topP?        : number;
+}): string {
+    // JSON of a fixed-order tuple — deterministic and unambiguous (a delimiter
+    // string could collide across fields; positional JSON cannot).
+    return JSON.stringify([
+        parts.model        ?? '',
+        parts.systemPrompt ?? '',
+        parts.maxTokens    ?? '',
+        parts.temperature  ?? '',
+        parts.topP         ?? '',
+        parts.prompt,
+    ]);
+}

package/src/bridges/SemanticCachingBridge.ts

@@ -0,0 +1,60 @@
+/**
+ * SemanticCachingBridge – a read-through *semantic* caching decorator for any
+ * TransformerBridge. The semantic sibling of CachingBridge: where CachingBridge
+ * only reuses byte-identical prompts, this reuses a prior answer when the new
+ * prompt is within `threshold` cosine similarity of one already answered.
+ *
+ *   const bridge = new SemanticCachingBridge(new AnthropicBridge({ apiKey }), {
+ *     embed: (t) => runtime.embed(t),        // on-device SSM, free
+ *     l2: new FetchSemanticCacheBackend({ baseUrl, apiKey }),  // shared via gateway
+ *   });
+ *
+ * Streaming is delegated straight through and never cached.
+ */
+
+import type { TransformerBridge, BridgeGenerateOptions } from './TransformerBridge.js';
+import { SemanticCache, type SemanticCacheOptions } from '../cache/SemanticCache.js';
+
+export interface SemanticCachingBridgeOptions extends Omit<SemanticCacheOptions, never> {
+    /** Provide a shared SemanticCache instance instead of constructing one. */
+    cache? : SemanticCache;
+}
+
+export class SemanticCachingBridge implements TransformerBridge {
+    private readonly _inner : TransformerBridge;
+    private readonly _cache : SemanticCache;
+
+    constructor(inner: TransformerBridge, opts: SemanticCachingBridgeOptions) {
+        this._inner = inner;
+        this._cache = opts.cache ?? new SemanticCache(opts);
+    }
+
+    get supportsStreaming(): boolean {
+        return this._inner.supportsStreaming;
+    }
+
+    /** The underlying SemanticCache — exposed for stats inspection. */
+    get cache(): SemanticCache {
+        return this._cache;
+    }
+
+    async generate(prompt: string, opts: BridgeGenerateOptions = {}): Promise<string> {
+        // Match on system + prompt meaning so different system contexts don't
+        // cross-hit; partition further by model via the stored meta.
+        const queryText = opts.systemPrompt ? `${opts.systemPrompt}\n${prompt}` : prompt;
+        const { response } = await this._cache.getOrGenerate(
+            queryText,
+            () => this._inner.generate(prompt, opts),
+            opts.model ? { model: opts.model } : undefined,
+        );
+        return response;
+    }
+
+    /** Streaming is delegated unchanged and never cached. */
+    stream(prompt: string, opts?: BridgeGenerateOptions): AsyncIterable<string> {
+        if (!this._inner.stream) {
+            throw new Error('Wrapped bridge does not support streaming.');
+        }
+        return this._inner.stream(prompt, opts);
+    }
+}

package/src/bridges/TransformerBridge.ts

@@ -0,0 +1,38 @@
+/**
+ * TransformerBridge – pluggable interface for any transformer LLM backend.
+ *
+ * Implementations (OpenAIBridge, AnthropicBridge, FetchBridge) satisfy this
+ * interface and are passed to SSMRuntime to enable hybrid inference and
+ * distillation.  The interface is structural — any object with the right
+ * shape works, no base class required.
+ */
+
+export interface BridgeGenerateOptions {
+    /** Max tokens to generate. Default per-adapter (typically 512). */
+    maxTokens?    : number;
+    /** Sampling temperature. Default per-adapter (typically 0.7). */
+    temperature?  : number;
+    /** Nucleus sampling p. Default per-adapter (typically 0.9). */
+    topP?         : number;
+    /** System prompt for this request, overriding the adapter's default. */
+    systemPrompt? : string;
+    /** Model string, overriding the adapter's default. */
+    model?        : string;
+}
+
+export interface TransformerBridge {
+    /**
+     * Generates a completion for the given prompt.
+     * Must resolve to the assistant's reply text only (not including the prompt).
+     */
+    generate(prompt: string, opts?: BridgeGenerateOptions): Promise<string>;
+
+    /**
+     * Streaming variant — yields tokens incrementally.
+     * Check `supportsStreaming` before calling.
+     */
+    stream?(prompt: string, opts?: BridgeGenerateOptions): AsyncIterable<string>;
+
+    /** True when this bridge supports the `stream()` method. */
+    readonly supportsStreaming: boolean;
+}

package/src/bridges/index.ts

@@ -0,0 +1,13 @@
+export type { TransformerBridge, BridgeGenerateOptions } from './TransformerBridge.js';
+export { OpenAIBridge }    from './OpenAIBridge.js';
+export { AnthropicBridge } from './AnthropicBridge.js';
+export { FetchBridge }     from './FetchBridge.js';
+export { CachingBridge }   from './CachingBridge.js';
+export { SemanticCachingBridge } from './SemanticCachingBridge.js';
+export { ResponseCache, buildCacheKey } from './ResponseCache.js';
+export type { OpenAIBridgeOptions }    from './OpenAIBridge.js';
+export type { AnthropicBridgeOptions } from './AnthropicBridge.js';
+export type { FetchBridgeOptions }     from './FetchBridge.js';
+export type { CachingBridgeOptions }   from './CachingBridge.js';
+export type { SemanticCachingBridgeOptions } from './SemanticCachingBridge.js';
+export type { ResponseCacheOptions }   from './ResponseCache.js';

package/src/cache/FetchSemanticCacheBackend.ts

@@ -0,0 +1,79 @@
+/**
+ * FetchSemanticCacheBackend – the shared (L2) tier of the SemanticCache, backed
+ * by the BuilderForce.ai gateway's vector store over HTTP.
+ *
+ * One client used by both consumers (browser + agent) so a semantic hit on one
+ * surface is reusable by the other. Pure `fetch` — no environment-specific deps;
+ * inject `fetchImpl` in tests.
+ *
+ * Wire protocol (gateway `/v1/semantic-cache`):
+ *   POST /lookup  { embedding: number[], threshold, namespace? } → { hit?: { response, score } }
+ *   POST /store   { embedding: number[], response, namespace?, meta? } → 2xx
+ */
+
+import type { SemanticCacheBackend } from './SemanticCache.js';
+
+export interface FetchSemanticCacheBackendOptions {
+    /** Gateway base URL, e.g. 'https://api.builderforce.ai'. Trailing slash trimmed. */
+    baseUrl  : string;
+    /** Tenant API key (sent as a bearer token). */
+    apiKey   : string;
+    /**
+     * Optional cache partition. Scope hits to a tenant/model/agent so unrelated
+     * traffic can't cross-hit. Defaults to the gateway's per-tenant default.
+     */
+    namespace? : string;
+    /** Injectable fetch (defaults to global fetch). */
+    fetchImpl? : typeof fetch;
+}
+
+export class FetchSemanticCacheBackend implements SemanticCacheBackend {
+    private readonly _base      : string;
+    private readonly _apiKey    : string;
+    private readonly _namespace : string | undefined;
+    private readonly _fetch     : typeof fetch;
+
+    constructor(opts: FetchSemanticCacheBackendOptions) {
+        this._base      = opts.baseUrl.replace(/\/$/, '');
+        this._apiKey    = opts.apiKey;
+        this._namespace = opts.namespace;
+        this._fetch     = opts.fetchImpl ?? fetch;
+    }
+
+    async lookup(embedding: Float32Array, threshold: number): Promise<{ response: string; score: number } | undefined> {
+        const res = await this._fetch(`${this._base}/v1/semantic-cache/lookup`, {
+            method : 'POST',
+            headers: this._headers(),
+            body   : JSON.stringify({
+                embedding: Array.from(embedding),
+                threshold,
+                ...(this._namespace ? { namespace: this._namespace } : {}),
+            }),
+        });
+        if (!res.ok) return undefined;
+        const json = await res.json().catch(() => null) as { hit?: { response?: unknown; score?: unknown } } | null;
+        const hit = json?.hit;
+        if (!hit || typeof hit.response !== 'string' || typeof hit.score !== 'number') return undefined;
+        return { response: hit.response, score: hit.score };
+    }
+
+    async store(embedding: Float32Array, response: string, meta?: Record<string, unknown>): Promise<void> {
+        await this._fetch(`${this._base}/v1/semantic-cache/store`, {
+            method : 'POST',
+            headers: this._headers(),
+            body   : JSON.stringify({
+                embedding: Array.from(embedding),
+                response,
+                ...(this._namespace ? { namespace: this._namespace } : {}),
+                ...(meta ? { meta } : {}),
+            }),
+        });
+    }
+
+    private _headers(): Record<string, string> {
+        return {
+            'Content-Type' : 'application/json',
+            Authorization  : `Bearer ${this._apiKey}`,
+        };
+    }
+}

package/src/cache/SemanticCache.ts

@@ -0,0 +1,196 @@
+/**
+ * SemanticCache – an embedding-keyed read-through cache for LLM completions.
+ *
+ * Unlike the exact-match ResponseCache (which keys on the byte-identical prompt),
+ * this keys on the *meaning* of the query: it embeds the query and serves a
+ * cached answer when a stored entry is within `threshold` cosine similarity.
+ * That catches paraphrases — "fix the auth bug" ≈ "login is broken" — which is
+ * where real frontier-call avoidance (and token savings) comes from.
+ *
+ * Two tiers, mirroring the project's L1-in-process / L2-shared read-through
+ * pattern:
+ *   - L1: an in-process vector list, scanned locally (fast, offline-capable).
+ *   - L2: an optional shared backend (e.g. the BuilderForce.ai gateway vector
+ *         store) so a hit on one surface — web or agent — benefits the other.
+ *
+ * Fully portable: the embedder and the L2 backend are injected, so the same
+ * class runs in the browser (WebGPU SSM + native fetch) and in Node (the agent's
+ * `@webgpu/node` SSM + fetch) with no environment-specific forks.
+ */
+
+import { cosineSimilarity } from '../similarity/index.js';
+
+/** Produces an embedding vector for a piece of text (the on-device SSM, typically). */
+export type Embedder = (text: string) => Promise<Float32Array>;
+
+/**
+ * The shared (L2) cache tier. Implemented by `FetchSemanticCacheBackend` against
+ * the gateway, but any store satisfying this shape can be injected.
+ */
+export interface SemanticCacheBackend {
+    /** Returns the best stored entry at/above `threshold` cosine similarity, or undefined. */
+    lookup(embedding: Float32Array, threshold: number): Promise<{ response: string; score: number } | undefined>;
+    /** Persists an embedding → response association. */
+    store(embedding: Float32Array, response: string, meta?: Record<string, unknown>): Promise<void>;
+}
+
+export interface SemanticCacheHit {
+    response: string;
+    /** Cosine similarity of the matched entry to the query. */
+    score: number;
+    /** Which tier served the hit. */
+    tier: 'l1' | 'l2';
+}
+
+export interface SemanticCacheOptions {
+    /** Embeds queries. Required — this is what makes the cache semantic. */
+    embed: Embedder;
+    /**
+     * Cosine similarity at/above which a stored entry counts as a hit.
+     * Higher = stricter (fewer false hits, lower hit rate). Default: 0.92.
+     */
+    threshold?: number;
+    /** Max L1 entries retained (oldest evicted first). Default: 500. */
+    maxEntries?: number;
+    /** Optional TTL (ms) for L1 entries. Omit for no expiry. */
+    ttlMs?: number;
+    /** Optional shared L2 backend (e.g. the gateway). */
+    l2?: SemanticCacheBackend;
+    /**
+     * When true (default), an answer served by L2 is also written into L1 so the
+     * next local lookup is a fast hit — read-through cache warming.
+     */
+    warmL1FromL2?: boolean;
+}
+
+interface L1Entry { embedding: Float32Array; response: string; timestamp: number; }
+
+const DEFAULT_THRESHOLD   = 0.92;
+const DEFAULT_MAX_ENTRIES = 500;
+
+export class SemanticCache {
+    private readonly _embed      : Embedder;
+    private readonly _threshold  : number;
+    private readonly _maxEntries : number;
+    private readonly _ttlMs      : number | undefined;
+    private readonly _l2         : SemanticCacheBackend | undefined;
+    private readonly _warmL1     : boolean;
+    private readonly _l1         : L1Entry[] = [];
+
+    private _l1Hits = 0;
+    private _l2Hits = 0;
+    private _misses = 0;
+
+    constructor(opts: SemanticCacheOptions) {
+        this._embed      = opts.embed;
+        this._threshold  = opts.threshold  ?? DEFAULT_THRESHOLD;
+        this._maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        this._ttlMs      = opts.ttlMs;
+        this._l2         = opts.l2;
+        this._warmL1     = opts.warmL1FromL2 ?? true;
+    }
+
+    /**
+     * Read-through entry point: returns a cached answer for a semantically-similar
+     * prior query, otherwise runs `generate()`, stores the result in both tiers,
+     * and returns it. Embeds the query exactly once (lookup + store share it).
+     */
+    async getOrGenerate(
+        query: string,
+        generate: () => Promise<string>,
+        meta?: Record<string, unknown>,
+    ): Promise<{ response: string; cached: boolean; tier?: 'l1' | 'l2'; score?: number }> {
+        const qv  = await this._embed(query);
+        const hit = await this._lookupVec(qv);
+        if (hit) return { response: hit.response, cached: true, tier: hit.tier, score: hit.score };
+
+        const response = await generate();
+        await this._storeVec(qv, response, meta);
+        return { response, cached: false };
+    }
+
+    /** Looks up a semantically-similar cached answer without generating on a miss. */
+    async lookup(query: string): Promise<SemanticCacheHit | undefined> {
+        return this._lookupVec(await this._embed(query));
+    }
+
+    /** Stores a query → response association in both tiers. */
+    async store(query: string, response: string, meta?: Record<string, unknown>): Promise<void> {
+        await this._storeVec(await this._embed(query), response, meta);
+    }
+
+    /** Drops all L1 entries. Does not touch the shared L2 backend. */
+    clear(): void {
+        this._l1.length = 0;
+    }
+
+    /** Current L1 entry count. */
+    get size(): number {
+        return this._l1.length;
+    }
+
+    /** Cumulative hit/miss counters across both tiers — for measuring savings. */
+    get stats(): { l1Hits: number; l2Hits: number; misses: number } {
+        return { l1Hits: this._l1Hits, l2Hits: this._l2Hits, misses: this._misses };
+    }
+
+    // ── Internals (operate on a precomputed embedding) ────────────────────────
+
+    private async _lookupVec(qv: Float32Array): Promise<SemanticCacheHit | undefined> {
+        const local = this._searchL1(qv);
+        if (local) {
+            this._l1Hits++;
+            return { response: local.response, score: local.score, tier: 'l1' };
+        }
+
+        if (this._l2) {
+            // L2 is best-effort: a gateway error degrades to local-only, never throws.
+            const remote = await this._l2.lookup(qv, this._threshold).catch(() => undefined);
+            if (remote && remote.score >= this._threshold) {
+                if (this._warmL1) this._addL1(qv, remote.response);
+                this._l2Hits++;
+                return { response: remote.response, score: remote.score, tier: 'l2' };
+            }
+        }
+
+        this._misses++;
+        return undefined;
+    }
+
+    private async _storeVec(qv: Float32Array, response: string, meta?: Record<string, unknown>): Promise<void> {
+        this._addL1(qv, response);
+        if (this._l2) {
+            // Best-effort: failing to share to L2 must not fail the caller's request.
+            await this._l2.store(qv, response, meta).catch(() => { /* swallow — local copy still cached */ });
+        }
+    }
+
+    /** Linear cosine scan over L1, dropping expired entries en route. */
+    private _searchL1(qv: Float32Array): { response: string; score: number } | undefined {
+        const now = Date.now();
+        let best: L1Entry | undefined;
+        let bestScore = -Infinity;
+
+        for (let i = this._l1.length - 1; i >= 0; i--) {
+            const entry = this._l1[i]!;
+            if (this._ttlMs != null && now > entry.timestamp + this._ttlMs) {
+                this._l1.splice(i, 1);
+                continue;
+            }
+            const score = cosineSimilarity(qv, entry.embedding);
+            if (score > bestScore) {
+                bestScore = score;
+                best = entry;
+            }
+        }
+
+        return best && bestScore >= this._threshold
+            ? { response: best.response, score: bestScore }
+            : undefined;
+    }
+
+    private _addL1(qv: Float32Array, response: string): void {
+        this._l1.push({ embedding: qv, response, timestamp: Date.now() });
+        while (this._l1.length > this._maxEntries) this._l1.shift();
+    }
+}

package/src/cache/index.ts

@@ -0,0 +1,9 @@
+export { SemanticCache } from './SemanticCache.js';
+export type {
+    Embedder,
+    SemanticCacheBackend,
+    SemanticCacheHit,
+    SemanticCacheOptions,
+} from './SemanticCache.js';
+export { FetchSemanticCacheBackend } from './FetchSemanticCacheBackend.js';
+export type { FetchSemanticCacheBackendOptions } from './FetchSemanticCacheBackend.js';