@mars167/git-ai 2.3.0

package/dist/src/core/indexing/hnsw.js

@@ -0,0 +1,568 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HNSWIndex = void 0;
+exports.clampHnswParameters = clampHnswParameters;
+exports.quantize = quantize;
+exports.dequantize = dequantize;
+exports.cosineSimilarity = cosineSimilarity;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const sq8_1 = require("../sq8");
+const HNSW_MAGIC = Buffer.from('HNSW');
+const HNSW_VERSION = 1;
+function writeUInt32(value) {
+    const buf = Buffer.allocUnsafe(4);
+    buf.writeUInt32LE(value >>> 0, 0);
+    return buf;
+}
+function writeFloat32(value) {
+    const buf = Buffer.allocUnsafe(4);
+    buf.writeFloatLE(value, 0);
+    return buf;
+}
+function writeString(value) {
+    const bytes = Buffer.from(value, 'utf-8');
+    return [writeUInt32(bytes.length), bytes];
+}
+function assertAvailable(buf, offset, size) {
+    if (offset + size > buf.length) {
+        throw new Error('HNSW index file is truncated');
+    }
+}
+function readUInt32(buf, state) {
+    assertAvailable(buf, state.offset, 4);
+    const value = buf.readUInt32LE(state.offset);
+    state.offset += 4;
+    return value;
+}
+function readFloat32(buf, state) {
+    assertAvailable(buf, state.offset, 4);
+    const value = buf.readFloatLE(state.offset);
+    state.offset += 4;
+    return value;
+}
+function readString(buf, state) {
+    const length = readUInt32(buf, state);
+    if (length === 0)
+        return '';
+    assertAvailable(buf, state.offset, length);
+    const value = buf.toString('utf-8', state.offset, state.offset + length);
+    state.offset += length;
+    return value;
+}
+function copyInt8Slice(buf, offset, length) {
+    assertAvailable(buf, offset, length);
+    const slice = buf.subarray(offset, offset + length);
+    const out = new Int8Array(length);
+    out.set(slice);
+    return out;
+}
+class HNSWIndex {
+    constructor(config) {
+        const clamped = clampHnswParameters(config);
+        const dim = typeof config.dim === 'number' && Number.isFinite(config.dim) ? config.dim : 0;
+        this.config = { ...clamped, dim, maxElements: config.maxElements };
+        this.nodes = new Map();
+        this.entryPoint = null;
+        this.maxLevel = 0;
+        this.levelMult = this.computeLevelMult();
+        this.dim = dim > 0 ? dim : undefined;
+        this.levelCap = this.computeLevelCap();
+    }
+    getConfig() {
+        return { ...this.config };
+    }
+    getCount() {
+        return this.nodes.size;
+    }
+    size() {
+        return this.getCount();
+    }
+    add(arg1, arg2) {
+        const entry = typeof arg1 === 'string' ? { id: arg1, vector: arg2 } : arg1;
+        if (!entry?.id)
+            throw new Error('HNSW entry id is required');
+        if (!entry.vector)
+            throw new Error('HNSW entry vector is required');
+        if (this.nodes.has(entry.id))
+            throw new Error(`HNSW entry already exists: ${entry.id}`);
+        if (this.config.maxElements && this.nodes.size >= this.config.maxElements) {
+            throw new Error('HNSW index is full');
+        }
+        this.ensureDim(entry.vector);
+        const level = this.selectLevel();
+        const node = {
+            id: entry.id,
+            vector: entry.vector,
+            level,
+            neighbors: new Map(),
+        };
+        this.nodes.set(node.id, node);
+        if (!this.entryPoint) {
+            this.entryPoint = { nodeId: node.id, level: node.level };
+            this.maxLevel = node.level;
+            return;
+        }
+        const entryPointLevel = this.entryPoint.level;
+        const insertLevel = Math.min(level, entryPointLevel);
+        let current = this.findInsertionPoint(entry.vector, insertLevel);
+        for (let layer = insertLevel; layer >= 0; layer--) {
+            const candidates = this.searchLayer(entry.vector, current, this.config.efConstruction, layer);
+            const neighbors = this.selectNeighbors(candidates, this.config.M, node.id);
+            this.connectNeighbors(node.id, neighbors, layer);
+            if (candidates.length > 0)
+                current = candidates[0].id;
+        }
+        if (node.level > this.maxLevel) {
+            this.entryPoint = { nodeId: node.id, level: node.level };
+            this.maxLevel = node.level;
+        }
+    }
+    addBatch(entries) {
+        if (entries.length === 0)
+            return;
+        for (const entry of entries)
+            this.add(entry);
+    }
+    search(query, k) {
+        if (!this.entryPoint)
+            return [];
+        if (k <= 0)
+            return [];
+        const limit = Math.max(1, k);
+        this.ensureDim(query);
+        let current = this.entryPoint.nodeId;
+        for (let level = this.entryPoint.level; level > 0; level--) {
+            const nearest = this.searchLayer(query, current, 1, level);
+            if (nearest.length > 0)
+                current = nearest[0].id;
+        }
+        const ef = Math.max(limit, this.config.efSearch);
+        const results = this.searchLayer(query, current, ef, 0);
+        return results.slice(0, limit);
+    }
+    searchBatch(queries, k) {
+        if (queries.length === 0)
+            return [];
+        return queries.map((query) => this.search(query, k));
+    }
+    async save(filePath) {
+        const pieces = [];
+        pieces.push(HNSW_MAGIC);
+        pieces.push(writeUInt32(HNSW_VERSION));
+        pieces.push(writeUInt32(this.config.M));
+        pieces.push(writeUInt32(this.config.efConstruction));
+        pieces.push(writeUInt32(this.config.efSearch));
+        pieces.push(writeUInt32(this.config.quantizationBits));
+        pieces.push(writeUInt32(this.dim ?? this.config.dim ?? 0));
+        pieces.push(writeUInt32(this.config.maxElements ?? 0));
+        pieces.push(writeUInt32(this.nodes.size));
+        pieces.push(writeUInt32(this.maxLevel));
+        for (const node of this.nodes.values()) {
+            pieces.push(...writeString(node.id));
+            pieces.push(writeUInt32(node.level));
+            pieces.push(writeUInt32(node.vector.dim));
+            pieces.push(writeFloat32(node.vector.scale));
+            const qBuffer = Buffer.from(node.vector.q.buffer, node.vector.q.byteOffset, node.vector.q.byteLength);
+            pieces.push(qBuffer);
+            const neighborsByLevel = Array.from(node.neighbors.entries());
+            pieces.push(writeUInt32(neighborsByLevel.length));
+            for (const [level, neighbors] of neighborsByLevel) {
+                pieces.push(writeUInt32(level));
+                pieces.push(writeUInt32(neighbors.size));
+                for (const [neighborId, distance] of neighbors) {
+                    pieces.push(...writeString(neighborId));
+                    pieces.push(writeFloat32(distance));
+                }
+            }
+        }
+        if (this.entryPoint) {
+            pieces.push(...writeString(this.entryPoint.nodeId));
+            pieces.push(writeUInt32(this.entryPoint.level));
+        }
+        else {
+            pieces.push(writeUInt32(0));
+            pieces.push(writeUInt32(0));
+        }
+        const output = Buffer.concat(pieces);
+        await fs_extra_1.default.ensureDir(path_1.default.dirname(filePath));
+        await fs_extra_1.default.writeFile(filePath, output);
+    }
+    async load(filePath) {
+        const data = await fs_extra_1.default.readFile(filePath);
+        const state = { offset: 0 };
+        assertAvailable(data, state.offset, HNSW_MAGIC.length);
+        const magic = data.subarray(state.offset, state.offset + HNSW_MAGIC.length);
+        state.offset += HNSW_MAGIC.length;
+        if (!magic.equals(HNSW_MAGIC)) {
+            throw new Error('Invalid HNSW index file');
+        }
+        const version = readUInt32(data, state);
+        if (version !== HNSW_VERSION) {
+            throw new Error(`Unsupported HNSW index version: ${version}`);
+        }
+        const M = readUInt32(data, state);
+        const efConstruction = readUInt32(data, state);
+        const efSearch = readUInt32(data, state);
+        const quantizationBits = readUInt32(data, state);
+        const dim = readUInt32(data, state);
+        const maxElements = readUInt32(data, state) || undefined;
+        const nodeCount = readUInt32(data, state);
+        const headerMaxLevel = readUInt32(data, state);
+        const config = {
+            M,
+            efConstruction,
+            efSearch,
+            quantizationBits,
+            dim: dim || undefined,
+            maxElements,
+        };
+        const nodes = new Map();
+        let maxLevel = headerMaxLevel;
+        let highest = null;
+        for (let i = 0; i < nodeCount; i++) {
+            const id = readString(data, state);
+            const level = readUInt32(data, state);
+            const vecDim = readUInt32(data, state);
+            const scale = readFloat32(data, state);
+            const q = copyInt8Slice(data, state.offset, vecDim);
+            state.offset += vecDim;
+            if (dim && vecDim !== dim) {
+                throw new Error(`HNSW node dim mismatch: expected ${dim}, got ${vecDim}`);
+            }
+            const neighborsByLevelCount = readUInt32(data, state);
+            const neighbors = new Map();
+            for (let j = 0; j < neighborsByLevelCount; j++) {
+                const levelId = readUInt32(data, state);
+                const neighborCount = readUInt32(data, state);
+                const map = new Map();
+                for (let k = 0; k < neighborCount; k++) {
+                    const neighborId = readString(data, state);
+                    const distance = readFloat32(data, state);
+                    map.set(neighborId, distance);
+                }
+                neighbors.set(levelId, map);
+            }
+            const node = {
+                id,
+                level,
+                vector: { dim: vecDim, scale, q },
+                neighbors,
+            };
+            nodes.set(id, node);
+            if (!highest || level > highest.level)
+                highest = { nodeId: id, level };
+            if (level > maxLevel)
+                maxLevel = level;
+        }
+        const entryId = readString(data, state);
+        const entryLevel = readUInt32(data, state);
+        let entryPoint = null;
+        if (entryId) {
+            if (!nodes.has(entryId)) {
+                throw new Error(`HNSW entry point not found: ${entryId}`);
+            }
+            const entryNode = nodes.get(entryId);
+            if (entryNode && entryLevel > entryNode.level) {
+                throw new Error(`HNSW entry point level mismatch: ${entryLevel} > ${entryNode.level}`);
+            }
+            entryPoint = { nodeId: entryId, level: entryLevel };
+        }
+        else if (highest) {
+            entryPoint = highest;
+        }
+        const clamped = clampHnswParameters(config);
+        const resolvedDim = dim || this.dim || 0;
+        this.config = { ...clamped, dim: resolvedDim, maxElements };
+        this.nodes = nodes;
+        this.entryPoint = entryPoint;
+        this.maxLevel = maxLevel;
+        this.dim = resolvedDim > 0 ? resolvedDim : undefined;
+        if (!this.dim && nodes.size > 0) {
+            const first = nodes.values().next().value;
+            this.dim = first?.vector.dim;
+        }
+        this.config.dim = this.dim ?? 0;
+        this.levelMult = this.computeLevelMult();
+        this.levelCap = this.computeLevelCap();
+    }
+    clear() {
+        this.nodes.clear();
+        this.entryPoint = null;
+        this.maxLevel = 0;
+        this.dim = this.config.dim;
+    }
+    stats() {
+        let edgeCount = 0;
+        let memoryUsage = 0;
+        for (const node of this.nodes.values()) {
+            memoryUsage += Buffer.byteLength(node.id, 'utf-8');
+            memoryUsage += node.vector.q.byteLength + 8;
+            for (const neighbors of node.neighbors.values()) {
+                edgeCount += neighbors.size;
+                for (const neighborId of neighbors.keys()) {
+                    memoryUsage += Buffer.byteLength(neighborId, 'utf-8') + 8;
+                }
+            }
+        }
+        return {
+            nodeCount: this.nodes.size,
+            edgeCount,
+            maxLevel: this.maxLevel,
+            memoryUsage,
+        };
+    }
+    toSnapshot() {
+        return {
+            config: { ...this.config },
+            nodes: Array.from(this.nodes.values()).map((node) => ({
+                id: node.id,
+                level: node.level,
+                dim: node.vector.dim,
+                scale: node.vector.scale,
+                qvec_b64: Buffer.from(node.vector.q).toString('base64'),
+                neighbors: Array.from(node.neighbors.entries()).map(([level, neighbors]) => ({
+                    level,
+                    items: Array.from(neighbors.entries()).map(([id, distance]) => ({ id, distance })),
+                })),
+            })),
+            entryPoint: this.entryPoint ? { ...this.entryPoint } : null,
+            maxLevel: this.maxLevel,
+        };
+    }
+    static fromSnapshot(snapshot) {
+        const index = new HNSWIndex(snapshot.config);
+        if (snapshot.entries && snapshot.entries.length > 0) {
+            for (const entry of snapshot.entries) {
+                index.add({
+                    id: entry.id,
+                    vector: {
+                        dim: entry.dim,
+                        scale: entry.scale,
+                        q: new Int8Array(Buffer.from(entry.qvec_b64, 'base64')),
+                    },
+                });
+            }
+            return index;
+        }
+        const nodes = snapshot.nodes ?? [];
+        for (const node of nodes) {
+            index.nodes.set(node.id, {
+                id: node.id,
+                level: node.level,
+                vector: {
+                    dim: node.dim,
+                    scale: node.scale,
+                    q: new Int8Array(Buffer.from(node.qvec_b64, 'base64')),
+                },
+                neighbors: new Map(node.neighbors.map((layer) => [
+                    layer.level,
+                    new Map(layer.items.map((item) => [item.id, item.distance])),
+                ])),
+            });
+        }
+        const entryPoint = snapshot.entryPoint ?? null;
+        index.entryPoint = entryPoint ? { ...entryPoint } : null;
+        index.maxLevel = snapshot.maxLevel ?? entryPoint?.level ?? 0;
+        if (index.nodes.size > 0 && index.maxLevel === 0) {
+            for (const node of index.nodes.values()) {
+                if (node.level > index.maxLevel)
+                    index.maxLevel = node.level;
+            }
+        }
+        if (!index.dim && index.nodes.size > 0) {
+            const first = index.nodes.values().next().value;
+            index.dim = first?.vector.dim;
+        }
+        index.config.dim = index.dim ?? 0;
+        index.levelMult = index.computeLevelMult();
+        index.levelCap = index.computeLevelCap();
+        return index;
+    }
+    ensureDim(vector) {
+        if (!this.dim || this.dim === 0) {
+            this.dim = vector.dim;
+            this.config.dim = vector.dim;
+            return;
+        }
+        if (vector.dim !== this.dim) {
+            throw new Error(`HNSW vector dim mismatch: expected ${this.dim}, got ${vector.dim}`);
+        }
+        if (vector.q.length !== vector.dim) {
+            throw new Error(`HNSW quantized vector length mismatch: expected ${vector.dim}, got ${vector.q.length}`);
+        }
+    }
+    computeLevelMult() {
+        const M = Math.max(2, this.config.M);
+        const base = Math.log(M);
+        if (!Number.isFinite(base) || base === 0)
+            return 1;
+        return 1 / base;
+    }
+    computeLevelCap() {
+        if (!this.config.maxElements || this.config.maxElements <= 0)
+            return undefined;
+        const base = Math.log(Math.max(2, this.config.M));
+        if (!Number.isFinite(base) || base === 0)
+            return undefined;
+        const level = Math.ceil(Math.log(this.config.maxElements) / base);
+        return Math.max(0, level);
+    }
+    selectLevel() {
+        const r = Math.max(Number.EPSILON, Math.random());
+        const level = Math.floor(-Math.log(r) * this.levelMult);
+        if (this.levelCap == null)
+            return level;
+        return Math.min(level, this.levelCap);
+    }
+    selectNeighbors(candidates, M, excludeId) {
+        const limit = Math.max(1, M);
+        const sorted = candidates
+            .filter((c) => c.id !== excludeId)
+            .sort((a, b) => b.score - a.score);
+        const neighbors = [];
+        const seen = new Set();
+        for (const candidate of sorted) {
+            if (seen.has(candidate.id))
+                continue;
+            seen.add(candidate.id);
+            neighbors.push(candidate.id);
+            if (neighbors.length >= limit)
+                break;
+        }
+        return neighbors;
+    }
+    searchLayer(query, entryPoint, ef, level) {
+        const entryNode = this.nodes.get(entryPoint);
+        if (!entryNode)
+            return [];
+        const efSearch = Math.max(1, ef);
+        const queryVector = (0, sq8_1.dequantizeSQ8)(query);
+        const visited = new Set();
+        const candidates = [];
+        const top = [];
+        const entryScore = this.scoreWithQuery(queryVector, entryNode.vector);
+        const entryResult = { id: entryPoint, score: entryScore };
+        candidates.push(entryResult);
+        top.push(entryResult);
+        visited.add(entryPoint);
+        while (candidates.length > 0) {
+            candidates.sort((a, b) => b.score - a.score);
+            const current = candidates.shift();
+            top.sort((a, b) => b.score - a.score);
+            const worstTop = top[top.length - 1];
+            if (worstTop && current.score < worstTop.score && top.length >= efSearch) {
+                break;
+            }
+            const currentNode = this.nodes.get(current.id);
+            if (!currentNode)
+                continue;
+            const neighborMap = currentNode.neighbors.get(level);
+            if (!neighborMap)
+                continue;
+            for (const neighborId of neighborMap.keys()) {
+                if (visited.has(neighborId))
+                    continue;
+                visited.add(neighborId);
+                const neighborNode = this.nodes.get(neighborId);
+                if (!neighborNode)
+                    continue;
+                const score = this.scoreWithQuery(queryVector, neighborNode.vector);
+                const candidate = { id: neighborId, score };
+                if (top.length < efSearch) {
+                    candidates.push(candidate);
+                    top.push(candidate);
+                    continue;
+                }
+                top.sort((a, b) => b.score - a.score);
+                const worst = top[top.length - 1];
+                if (worst && score > worst.score) {
+                    candidates.push(candidate);
+                    top.push(candidate);
+                    top.sort((a, b) => b.score - a.score);
+                    while (top.length > efSearch)
+                        top.pop();
+                }
+            }
+        }
+        top.sort((a, b) => b.score - a.score);
+        return top;
+    }
+    findInsertionPoint(query, level) {
+        if (!this.entryPoint)
+            throw new Error('HNSW index is empty');
+        let current = this.entryPoint.nodeId;
+        for (let l = this.entryPoint.level; l > level; l--) {
+            const results = this.searchLayer(query, current, 1, l);
+            if (results.length > 0)
+                current = results[0].id;
+        }
+        return current;
+    }
+    connectNeighbors(nodeId, neighbors, level) {
+        const node = this.nodes.get(nodeId);
+        if (!node)
+            return;
+        const nodeNeighbors = this.getNeighborMap(node, level);
+        for (const neighborId of neighbors) {
+            const neighborNode = this.nodes.get(neighborId);
+            if (!neighborNode)
+                continue;
+            const distance = this.distanceBetweenVectors(node.vector, neighborNode.vector);
+            nodeNeighbors.set(neighborId, distance);
+            const neighborMap = this.getNeighborMap(neighborNode, level);
+            neighborMap.set(nodeId, distance);
+            if (neighborMap.size > this.config.M) {
+                neighborNode.neighbors.set(level, this.pruneNeighbors(neighborMap, this.config.M));
+            }
+        }
+        if (nodeNeighbors.size > this.config.M) {
+            node.neighbors.set(level, this.pruneNeighbors(nodeNeighbors, this.config.M));
+        }
+    }
+    getNeighborMap(node, level) {
+        const existing = node.neighbors.get(level);
+        if (existing)
+            return existing;
+        const map = new Map();
+        node.neighbors.set(level, map);
+        return map;
+    }
+    pruneNeighbors(neighbors, max) {
+        if (neighbors.size <= max)
+            return neighbors;
+        const sorted = Array.from(neighbors.entries()).sort((a, b) => a[1] - b[1]).slice(0, max);
+        return new Map(sorted);
+    }
+    scoreWithQuery(queryVector, vector) {
+        return (0, sq8_1.cosineSimilarity)(queryVector, (0, sq8_1.dequantizeSQ8)(vector));
+    }
+    scoreBetweenVectors(a, b) {
+        return (0, sq8_1.cosineSimilarity)((0, sq8_1.dequantizeSQ8)(a), (0, sq8_1.dequantizeSQ8)(b));
+    }
+    distanceBetweenVectors(a, b) {
+        return 1 - this.scoreBetweenVectors(a, b);
+    }
+}
+exports.HNSWIndex = HNSWIndex;
+function clampHnswParameters(config) {
+    return {
+        M: Math.max(2, Math.round(config.M)),
+        efConstruction: Math.max(10, Math.round(config.efConstruction)),
+        efSearch: Math.max(10, Math.round(config.efSearch)),
+        quantizationBits: Math.max(4, Math.min(8, Math.round(config.quantizationBits))),
+    };
+}
+function quantize(vector, bits = 8, id = '') {
+    const q = (0, sq8_1.quantizeSQ8)(vector, bits);
+    return { ...q, id };
+}
+function dequantize(q) {
+    return (0, sq8_1.dequantizeSQ8)(q);
+}
+function cosineSimilarity(a, b) {
+    return (0, sq8_1.cosineSimilarity)((0, sq8_1.dequantizeSQ8)(a), (0, sq8_1.dequantizeSQ8)(b));
+}

package/dist/src/core/indexing/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runParallelIndexing = exports.cosineSimilarity = exports.dequantize = exports.quantize = exports.clampHnswParameters = exports.HNSWIndex = exports.MemoryMonitor = exports.defaultIndexingRuntimeConfig = exports.defaultErrorHandlingConfig = exports.defaultIndexingConfig = void 0;
+var config_1 = require("./config");
+Object.defineProperty(exports, "defaultIndexingConfig", { enumerable: true, get: function () { return config_1.defaultIndexingConfig; } });
+Object.defineProperty(exports, "defaultErrorHandlingConfig", { enumerable: true, get: function () { return config_1.defaultErrorHandlingConfig; } });
+Object.defineProperty(exports, "defaultIndexingRuntimeConfig", { enumerable: true, get: function () { return config_1.defaultIndexingRuntimeConfig; } });
+var monitor_1 = require("./monitor");
+Object.defineProperty(exports, "MemoryMonitor", { enumerable: true, get: function () { return monitor_1.MemoryMonitor; } });
+var hnsw_1 = require("./hnsw");
+Object.defineProperty(exports, "HNSWIndex", { enumerable: true, get: function () { return hnsw_1.HNSWIndex; } });
+Object.defineProperty(exports, "clampHnswParameters", { enumerable: true, get: function () { return hnsw_1.clampHnswParameters; } });
+Object.defineProperty(exports, "quantize", { enumerable: true, get: function () { return hnsw_1.quantize; } });
+Object.defineProperty(exports, "dequantize", { enumerable: true, get: function () { return hnsw_1.dequantize; } });
+Object.defineProperty(exports, "cosineSimilarity", { enumerable: true, get: function () { return hnsw_1.cosineSimilarity; } });
+var parallel_1 = require("./parallel");
+Object.defineProperty(exports, "runParallelIndexing", { enumerable: true, get: function () { return parallel_1.runParallelIndexing; } });

package/dist/src/core/indexing/monitor.js

@@ -0,0 +1,82 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryMonitor = void 0;
+exports.getSystemMemoryBudgetMb = getSystemMemoryBudgetMb;
+const os_1 = __importDefault(require("os"));
+class MemoryMonitor {
+    constructor(config) {
+        this.budgetMb = Math.max(1, config.budgetMb);
+        this.warnThreshold = clamp(config.warningThreshold, 0, 1);
+        this.criticalThreshold = clamp(config.criticalThreshold, 0, 1);
+        this.lastSnapshot = null;
+    }
+    static fromErrorConfig(config, budgetMb) {
+        return new MemoryMonitor({
+            budgetMb,
+            warningThreshold: config.memoryWarningThreshold,
+            criticalThreshold: config.memoryCriticalThreshold,
+        });
+    }
+    sample() {
+        const mem = process.memoryUsage();
+        const rssMb = bytesToMb(mem.rss);
+        const heapUsedMb = bytesToMb(mem.heapUsed);
+        const heapTotalMb = bytesToMb(mem.heapTotal);
+        const externalMb = bytesToMb(mem.external ?? 0);
+        const usageRatio = this.budgetMb > 0 ? rssMb / this.budgetMb : 0;
+        const warning = usageRatio >= this.warnThreshold;
+        const critical = usageRatio >= this.criticalThreshold;
+        const snapshot = {
+            rssMb,
+            heapUsedMb,
+            heapTotalMb,
+            externalMb,
+            budgetMb: this.budgetMb,
+            usageRatio,
+            warning,
+            critical,
+        };
+        this.lastSnapshot = snapshot;
+        return snapshot;
+    }
+    getLastSnapshot() {
+        return this.lastSnapshot;
+    }
+    shouldThrottle() {
+        return Boolean(this.lastSnapshot?.critical);
+    }
+    async throttleIfNeeded() {
+        if (!this.shouldThrottle())
+            return;
+        const delayMs = Math.min(250, Math.max(25, Math.round((this.lastSnapshot?.usageRatio ?? 1) * 50)));
+        await sleep(delayMs);
+    }
+    adaptWorkerCount(current) {
+        if (!this.lastSnapshot)
+            return current;
+        if (this.lastSnapshot.critical)
+            return Math.max(1, Math.floor(current / 2));
+        if (this.lastSnapshot.warning)
+            return Math.max(1, current - 1);
+        return current;
+    }
+}
+exports.MemoryMonitor = MemoryMonitor;
+function getSystemMemoryBudgetMb() {
+    const total = bytesToMb(os_1.default.totalmem());
+    return Math.max(256, Math.floor(total * 0.5));
+}
+function bytesToMb(bytes) {
+    return Math.round(bytes / (1024 * 1024));
+}
+function clamp(value, min, max) {
+    if (Number.isNaN(value))
+        return min;
+    return Math.max(min, Math.min(max, value));
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}