@darkiceinteractive/mcp-conductor 2.0.0-alpha.1 → 3.0.0-beta.2

package/dist/cache/disk.js

@@ -0,0 +1,238 @@
+/**
+ * Persistent disk cache tier using CBOR encoding (cbor-x).
+ *
+ * Layout on disk:
+ *   <diskDir>/<sha256-prefix-2>/<full-argsHash>.cbor
+ *
+ * TTL enforcement is the responsibility of the caller (CacheLayer). DiskCache
+ * returns entries regardless of TTL so that stale-while-revalidate can be
+ * handled at the CacheLayer level.
+ *
+ * Parallel writes are safe: each key maps to a unique path; writes are
+ * atomic via a temp-file rename pattern.
+ *
+ * @module cache/disk
+ */
+import { readFile, writeFile, mkdir, readdir, stat, unlink, rename } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { encode as cborEncode, decode as cborDecode } from 'cbor-x';
+import { logger } from '../utils/index.js';
+const ROTATION_TARGET_RATIO = 0.8;
+export class DiskCache {
+    diskDir;
+    maxDiskBytes;
+    hits = 0;
+    misses = 0;
+    bytesOnDisk = 0;
+    ready;
+    constructor(options) {
+        this.diskDir = options.diskDir;
+        this.maxDiskBytes = options.maxDiskBytes ?? 2 * 1024 * 1024 * 1024;
+        this.ready = mkdir(this.diskDir, { recursive: true }).then(() => undefined);
+    }
+    async ensureReady() {
+        await this.ready;
+    }
+    entryPath(argsHash) {
+        const prefix = argsHash.substring(0, 2);
+        return join(this.diskDir, prefix, `${argsHash}.cbor`);
+    }
+    /**
+     * Read an entry from disk.
+     * Returns null only on genuine miss or read errors — TTL is NOT enforced here.
+     * CacheLayer is responsible for staleness decisions (enabling SWR to work).
+     */
+    async get(argsHash) {
+        await this.ensureReady();
+        const path = this.entryPath(argsHash);
+        try {
+            const buf = await readFile(path);
+            const entry = cborDecode(buf);
+            this.hits++;
+            return {
+                value: entry.value,
+                storedAt: entry.storedAt,
+                source: 'disk',
+                staleness: Date.now() - entry.storedAt,
+                ttlMs: entry.ttlMs,
+            };
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT') {
+                logger.debug('DiskCache: read error', { path, error: String(err) });
+            }
+            this.misses++;
+            return null;
+        }
+    }
+    /**
+     * Write an entry to disk atomically (write to .tmp then rename).
+     * Triggers rotation when over maxDiskBytes.
+     */
+    async set(argsHash, entry) {
+        await this.ensureReady();
+        const path = this.entryPath(argsHash);
+        const tmpPath = `${path}.tmp.${process.pid}`;
+        await mkdir(dirname(path), { recursive: true });
+        const buf = cborEncode(entry);
+        await writeFile(tmpPath, buf);
+        await rename(tmpPath, path);
+        this.bytesOnDisk += buf.byteLength;
+        if (this.bytesOnDisk > this.maxDiskBytes) {
+            this.rotate().catch((err) => logger.warn('DiskCache: rotation error', { error: String(err) }));
+        }
+    }
+    async delete(argsHash) {
+        await this.ensureReady();
+        const path = this.entryPath(argsHash);
+        try {
+            const s = await stat(path);
+            await unlink(path);
+            this.bytesOnDisk = Math.max(0, this.bytesOnDisk - s.size);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async invalidateByPrefix(serverToolPrefix) {
+        await this.ensureReady();
+        return this.scanAndDelete(async (entry, filePath) => {
+            const entryKey = `${entry.server}:${entry.tool}`;
+            const normalizedPrefix = serverToolPrefix.endsWith(':')
+                ? serverToolPrefix.slice(0, -1)
+                : serverToolPrefix;
+            // Match: entryKey starts with prefix (handles server-only and server:tool prefixes)
+            if (entryKey.startsWith(normalizedPrefix)) {
+                try {
+                    const s = await stat(filePath);
+                    await unlink(filePath);
+                    this.bytesOnDisk = Math.max(0, this.bytesOnDisk - s.size);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            }
+            return false;
+        });
+    }
+    async invalidateServer(server) {
+        await this.ensureReady();
+        return this.scanAndDelete(async (entry, filePath) => {
+            if (entry.server === server) {
+                try {
+                    const s = await stat(filePath);
+                    await unlink(filePath);
+                    this.bytesOnDisk = Math.max(0, this.bytesOnDisk - s.size);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            }
+            return false;
+        });
+    }
+    async clear() {
+        await this.ensureReady();
+        await this.scanAndDelete(async (_entry, filePath) => {
+            try {
+                await unlink(filePath);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+        this.bytesOnDisk = 0;
+    }
+    get approximateBytesOnDisk() { return this.bytesOnDisk; }
+    getCounters() { return { hits: this.hits, misses: this.misses }; }
+    async scanAndDelete(predicate) {
+        let count = 0;
+        let prefixDirs;
+        try {
+            prefixDirs = await readdir(this.diskDir);
+        }
+        catch {
+            return 0;
+        }
+        await Promise.all(prefixDirs.map(async (prefix) => {
+            const prefixPath = join(this.diskDir, prefix);
+            let files;
+            try {
+                const s = await stat(prefixPath);
+                if (!s.isDirectory())
+                    return;
+                files = await readdir(prefixPath);
+            }
+            catch {
+                return;
+            }
+            await Promise.all(files.filter((f) => f.endsWith('.cbor')).map(async (f) => {
+                const filePath = join(prefixPath, f);
+                try {
+                    const buf = await readFile(filePath);
+                    const entry = cborDecode(buf);
+                    const deleted = await predicate(entry, filePath);
+                    if (deleted)
+                        count++;
+                }
+                catch { /* corrupt — skip */ }
+            }));
+        }));
+        return count;
+    }
+    async rotate() {
+        const target = Math.floor(this.maxDiskBytes * ROTATION_TARGET_RATIO);
+        if (this.bytesOnDisk <= target)
+            return;
+        const entries = [];
+        let prefixDirs;
+        try {
+            prefixDirs = await readdir(this.diskDir);
+        }
+        catch {
+            return;
+        }
+        await Promise.all(prefixDirs.map(async (prefix) => {
+            const prefixPath = join(this.diskDir, prefix);
+            let files;
+            try {
+                const s = await stat(prefixPath);
+                if (!s.isDirectory())
+                    return;
+                files = await readdir(prefixPath);
+            }
+            catch {
+                return;
+            }
+            await Promise.all(files.filter((f) => f.endsWith('.cbor')).map(async (f) => {
+                const filePath = join(prefixPath, f);
+                try {
+                    const s = await stat(filePath);
+                    const buf = await readFile(filePath);
+                    const entry = cborDecode(buf);
+                    entries.push({ filePath, storedAt: entry.storedAt, size: s.size });
+                }
+                catch { /* skip */ }
+            }));
+        }));
+        entries.sort((a, b) => a.storedAt - b.storedAt);
+        let freed = 0;
+        const toFree = this.bytesOnDisk - target;
+        for (const e of entries) {
+            if (freed >= toFree)
+                break;
+            try {
+                await unlink(e.filePath);
+                freed += e.size;
+                this.bytesOnDisk = Math.max(0, this.bytesOnDisk - e.size);
+            }
+            catch { /* concurrent delete — ok */ }
+        }
+        logger.debug('DiskCache: rotated', { freedBytes: freed });
+    }
+}
+//# sourceMappingURL=disk.js.map

package/dist/cache/disk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"disk.js","sourceRoot":"","sources":["../../src/cache/disk.ts"],"names":[],"mappings":"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"}

package/dist/cache/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Public API for the MCP Conductor cache layer.
+ * Three-tier cache: in-memory LRU → persistent CBOR disk → delta encoding.
+ * @module cache
+ */
+export interface CacheKey {
+    server: string;
+    tool: string;
+    argsHash: string;
+}
+export interface CacheHit {
+    value: unknown;
+    storedAt: number;
+    source: 'memory' | 'disk';
+    staleness: number;
+}
+export interface CacheStats {
+    memoryHits: number;
+    diskHits: number;
+    misses: number;
+    evictions: number;
+    bytesInMemory: number;
+    bytesOnDisk: number;
+}
+export interface DeltaResult {
+    unchanged: boolean;
+    added?: unknown[];
+    removed?: unknown[];
+    modified?: Array<{
+        before: unknown;
+        after: unknown;
+    }>;
+    full?: unknown;
+}
+export interface CacheLayerOptions {
+    registry: import('../registry/registry.js').ToolRegistry;
+    diskDir?: string;
+    maxMemoryBytes?: number;
+    maxDiskBytes?: number;
+    staleWhileRevalidate?: boolean;
+    policies?: import('./policy.js').ServerPolicies;
+}
+export { CacheLayer } from './cache.js';
+export type { ExtendedCacheHit } from './cache.js';
+export { MemoryLru } from './lru.js';
+export type { LruOptions, LruEntry } from './lru.js';
+export { DiskCache } from './disk.js';
+export type { DiskCacheOptions, DiskEntry, DiskCacheHit } from './disk.js';
+export { stableJsonStringify, hashArgs, buildCacheKey, cacheKeyToString, parseCacheKey } from './key.js';
+export { resolveTtl, isCacheable, defaultTtlForName, DEFAULT_TTL_MS } from './policy.js';
+export type { ServerPolicies } from './policy.js';
+export { computeDelta, deepEqual } from './delta.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IACpB,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACtD,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,OAAO,yBAAyB,EAAE,YAAY,CAAC;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,EAAE,OAAO,aAAa,EAAE,cAAc,CAAC;CACjD;AAED,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,YAAY,EAAE,gBAAgB,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC3E,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzG,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACzF,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}

package/dist/cache/index.js

@@ -0,0 +1,12 @@
+/**
+ * Public API for the MCP Conductor cache layer.
+ * Three-tier cache: in-memory LRU → persistent CBOR disk → delta encoding.
+ * @module cache
+ */
+export { CacheLayer } from './cache.js';
+export { MemoryLru } from './lru.js';
+export { DiskCache } from './disk.js';
+export { stableJsonStringify, hashArgs, buildCacheKey, cacheKeyToString, parseCacheKey } from './key.js';
+export { resolveTtl, isCacheable, defaultTtlForName, DEFAULT_TTL_MS } from './policy.js';
+export { computeDelta, deepEqual } from './delta.js';
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAyCH,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzG,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEzF,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}

package/dist/cache/key.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Content-addressed cache key derivation.
+ *
+ * Keys are stable across process restarts: the same args always produce the
+ * same hash regardless of JS object-key insertion order. Schema-normalised
+ * args (via the registry validator) are used so that semantically-equivalent
+ * calls with differently-ordered properties hash identically.
+ *
+ * Format: `${server}:${tool}:${sha256hex(stableJsonStringify(args))}`
+ *
+ * @module cache/key
+ */
+import type { CacheKey } from './index.js';
+/**
+ * Stable JSON stringify — sorts object keys recursively so that key ordering
+ * differences between calls do not produce different hashes.
+ *
+ * Handles:
+ * - Objects (sorted keys)
+ * - Arrays (order preserved — array order IS semantically meaningful)
+ * - Primitives (null, boolean, number, string, undefined → JSON-serialised)
+ * - Circular references: throws, same as JSON.stringify
+ */
+export declare function stableJsonStringify(value: unknown): string;
+/**
+ * SHA-256 hex digest of a stable-stringified value.
+ * The returned string is always 64 hex characters.
+ */
+export declare function hashArgs(args: unknown): string;
+/**
+ * Build a structured CacheKey from server, tool, and args.
+ */
+export declare function buildCacheKey(server: string, tool: string, args: unknown): CacheKey;
+/**
+ * Serialise a CacheKey to the string format used on disk and in memory maps.
+ * Format: `${server}:${tool}:${argsHash}`
+ */
+export declare function cacheKeyToString(key: CacheKey): string;
+/**
+ * Parse a stringified cache key back to a CacheKey struct.
+ * Returns null when the format is invalid.
+ */
+export declare function parseCacheKey(str: string): CacheKey | null;
+//# sourceMappingURL=key.d.ts.map

package/dist/cache/key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../../src/cache/key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE1D;AAkBD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAG9C;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,QAAQ,CAEnF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAEtD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAgB1D"}

package/dist/cache/key.js

@@ -0,0 +1,83 @@
+/**
+ * Content-addressed cache key derivation.
+ *
+ * Keys are stable across process restarts: the same args always produce the
+ * same hash regardless of JS object-key insertion order. Schema-normalised
+ * args (via the registry validator) are used so that semantically-equivalent
+ * calls with differently-ordered properties hash identically.
+ *
+ * Format: `${server}:${tool}:${sha256hex(stableJsonStringify(args))}`
+ *
+ * @module cache/key
+ */
+import { createHash } from 'node:crypto';
+/**
+ * Stable JSON stringify — sorts object keys recursively so that key ordering
+ * differences between calls do not produce different hashes.
+ *
+ * Handles:
+ * - Objects (sorted keys)
+ * - Arrays (order preserved — array order IS semantically meaningful)
+ * - Primitives (null, boolean, number, string, undefined → JSON-serialised)
+ * - Circular references: throws, same as JSON.stringify
+ */
+export function stableJsonStringify(value) {
+    return JSON.stringify(sortObjectKeys(value));
+}
+function sortObjectKeys(value) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value !== 'object')
+        return value;
+    if (Array.isArray(value)) {
+        return value.map(sortObjectKeys);
+    }
+    const sorted = {};
+    const keys = Object.keys(value).sort();
+    for (const k of keys) {
+        sorted[k] = sortObjectKeys(value[k]);
+    }
+    return sorted;
+}
+/**
+ * SHA-256 hex digest of a stable-stringified value.
+ * The returned string is always 64 hex characters.
+ */
+export function hashArgs(args) {
+    const str = stableJsonStringify(args ?? {});
+    return createHash('sha256').update(str, 'utf8').digest('hex');
+}
+/**
+ * Build a structured CacheKey from server, tool, and args.
+ */
+export function buildCacheKey(server, tool, args) {
+    return { server, tool, argsHash: hashArgs(args) };
+}
+/**
+ * Serialise a CacheKey to the string format used on disk and in memory maps.
+ * Format: `${server}:${tool}:${argsHash}`
+ */
+export function cacheKeyToString(key) {
+    return `${key.server}:${key.tool}:${key.argsHash}`;
+}
+/**
+ * Parse a stringified cache key back to a CacheKey struct.
+ * Returns null when the format is invalid.
+ */
+export function parseCacheKey(str) {
+    // Key has exactly 3 segments: server, tool, and a 64-char hex hash.
+    // Tool names may contain underscores; server names should not contain colons.
+    const firstColon = str.indexOf(':');
+    if (firstColon < 0)
+        return null;
+    const hashStart = str.lastIndexOf(':');
+    if (hashStart <= firstColon)
+        return null;
+    const server = str.substring(0, firstColon);
+    const tool = str.substring(firstColon + 1, hashStart);
+    const argsHash = str.substring(hashStart + 1);
+    if (!server || !tool || argsHash.length !== 64)
+        return null;
+    return { server, tool, argsHash };
+}
+//# sourceMappingURL=key.js.map

package/dist/cache/key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.js","sourceRoot":"","sources":["../../src/cache/key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,OAAO,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACxD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAE5C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACnC,CAAC;IAED,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAgC,CAAC,CAAC,IAAI,EAAE,CAAC;IAClE,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,CAAC,CAAC,CAAC,GAAG,cAAc,CAAE,KAAiC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAa;IACpC,MAAM,GAAG,GAAG,mBAAmB,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IAC5C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,IAAY,EAAE,IAAa;IACvE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;AACpD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAa;IAC5C,OAAO,GAAG,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;AACrD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,oEAAoE;IACpE,8EAA8E;IAC9E,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,UAAU,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAEhC,MAAM,SAAS,GAAG,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,SAAS,IAAI,UAAU;QAAE,OAAO,IAAI,CAAC;IAEzC,MAAM,MAAM,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,GAAG,CAAC,SAAS,CAAC,UAAU,GAAG,CAAC,EAAE,SAAS,CAAC,CAAC;IACtD,MAAM,QAAQ,GAAG,GAAG,CAAC,SAAS,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IAE9C,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,IAAI,QAAQ,CAAC,MAAM,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAE5D,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AACpC,CAAC"}

package/dist/cache/lru.d.ts

@@ -0,0 +1,57 @@
+/**
+ * In-memory LRU cache tier.
+ *
+ * Wraps `lru-cache` with byte-aware eviction. TTL is enforced manually via
+ * storedAt + ttlMs fields rather than lru-cache's built-in TTL, so that
+ * tests using vi.useFakeTimers() work correctly (lru-cache's internal TTL
+ * uses the real clock bypassing the fake timer).
+ *
+ * @module cache/lru
+ */
+import type { CacheHit } from './index.js';
+export interface LruEntry {
+    value: unknown;
+    storedAt: number;
+    ttlMs: number;
+}
+export interface LruOptions {
+    /** Maximum total byte size of all cached values (default: 100 MB). */
+    maxMemoryBytes?: number;
+}
+export declare class MemoryLru {
+    private cache;
+    private evictions;
+    private hits;
+    private misses;
+    constructor(options?: LruOptions);
+    /**
+     * Retrieve an entry. Returns null on miss or TTL expiry.
+     */
+    get(key: string): CacheHit | null;
+    /**
+     * Store a value. ttlMs of 0 means store without TTL expiry.
+     */
+    set(key: string, value: unknown, ttlMs: number): void;
+    /** Delete a single key. Returns true if the key existed. */
+    delete(key: string): boolean;
+    /**
+     * Delete all keys matching a prefix.
+     * Returns the count of deleted entries.
+     */
+    invalidateByPrefix(prefix: string): number;
+    /** Remove all entries. */
+    clear(): void;
+    /** Current total byte estimate across all entries. */
+    get bytesUsed(): number;
+    /** Number of entries currently held. */
+    get size(): number;
+    /** Expose counters for CacheStats aggregation. */
+    getCounters(): {
+        hits: number;
+        misses: number;
+        evictions: number;
+    };
+    /** Reset hit/miss/eviction counters (useful in tests). */
+    resetCounters(): void;
+}
+//# sourceMappingURL=lru.d.ts.map

package/dist/cache/lru.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lru.d.ts","sourceRoot":"","sources":["../../src/cache/lru.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAWD,qBAAa,SAAS;IACpB,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;gBAEP,OAAO,GAAE,UAAe;IAgBpC;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI;IAwBjC;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAKrD,4DAA4D;IAC5D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B;;;OAGG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAW1C,0BAA0B;IAC1B,KAAK,IAAI,IAAI;IAIb,sDAAsD;IACtD,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,wCAAwC;IACxC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,kDAAkD;IAClD,WAAW,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;IAIlE,0DAA0D;IAC1D,aAAa,IAAI,IAAI;CAKtB"}

package/dist/cache/lru.js

@@ -0,0 +1,112 @@
+/**
+ * In-memory LRU cache tier.
+ *
+ * Wraps `lru-cache` with byte-aware eviction. TTL is enforced manually via
+ * storedAt + ttlMs fields rather than lru-cache's built-in TTL, so that
+ * tests using vi.useFakeTimers() work correctly (lru-cache's internal TTL
+ * uses the real clock bypassing the fake timer).
+ *
+ * @module cache/lru
+ */
+import { LRUCache } from 'lru-cache';
+/** Estimate the serialised byte size of a value. */
+function estimateBytes(value) {
+    try {
+        return Buffer.byteLength(JSON.stringify(value) ?? 'null', 'utf8');
+    }
+    catch {
+        return 0;
+    }
+}
+export class MemoryLru {
+    cache;
+    evictions = 0;
+    hits = 0;
+    misses = 0;
+    constructor(options = {}) {
+        const maxSize = options.maxMemoryBytes ?? 100 * 1024 * 1024; // 100 MB
+        this.cache = new LRUCache({
+            maxSize,
+            sizeCalculation: (entry) => {
+                return Math.max(1, estimateBytes(entry.value));
+            },
+            allowStale: false,
+            updateAgeOnGet: true,
+            dispose: () => {
+                this.evictions++;
+            },
+        });
+    }
+    /**
+     * Retrieve an entry. Returns null on miss or TTL expiry.
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            this.misses++;
+            return null;
+        }
+        // Manual TTL check so fake timers work in tests
+        const now = Date.now();
+        if (entry.ttlMs > 0 && now - entry.storedAt > entry.ttlMs) {
+            this.cache.delete(key);
+            this.misses++;
+            return null;
+        }
+        this.hits++;
+        return {
+            value: entry.value,
+            storedAt: entry.storedAt,
+            source: 'memory',
+            staleness: now - entry.storedAt,
+        };
+    }
+    /**
+     * Store a value. ttlMs of 0 means store without TTL expiry.
+     */
+    set(key, value, ttlMs) {
+        const entry = { value, storedAt: Date.now(), ttlMs };
+        this.cache.set(key, entry);
+    }
+    /** Delete a single key. Returns true if the key existed. */
+    delete(key) {
+        return this.cache.delete(key);
+    }
+    /**
+     * Delete all keys matching a prefix.
+     * Returns the count of deleted entries.
+     */
+    invalidateByPrefix(prefix) {
+        let count = 0;
+        for (const key of this.cache.keys()) {
+            if (key.startsWith(prefix)) {
+                this.cache.delete(key);
+                count++;
+            }
+        }
+        return count;
+    }
+    /** Remove all entries. */
+    clear() {
+        this.cache.clear();
+    }
+    /** Current total byte estimate across all entries. */
+    get bytesUsed() {
+        return this.cache.calculatedSize ?? 0;
+    }
+    /** Number of entries currently held. */
+    get size() {
+        return this.cache.size;
+    }
+    /** Expose counters for CacheStats aggregation. */
+    getCounters() {
+        return { hits: this.hits, misses: this.misses, evictions: this.evictions };
+    }
+    /** Reset hit/miss/eviction counters (useful in tests). */
+    resetCounters() {
+        this.hits = 0;
+        this.misses = 0;
+        this.evictions = 0;
+    }
+}
+//# sourceMappingURL=lru.js.map

package/dist/cache/lru.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lru.js","sourceRoot":"","sources":["../../src/cache/lru.ts"],"names":[],"mappings":"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"}