grepmax 0.24.0 → 0.25.0

package/dist/lib/index/batch-processor.js

@@ -43,36 +43,44 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ProjectBatchProcessor = void 0;
-const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
-const config_1 = require("../../config");
 const vector_db_1 = require("../store/vector-db");
 const cache_check_1 = require("../utils/cache-check");
 const file_utils_1 = require("../utils/file-utils");
 const logger_1 = require("../utils/logger");
 const pool_1 = require("../workers/pool");
+const file_policy_1 = require("./file-policy");
 const watcher_batch_1 = require("./watcher-batch");
-// Fast path-segment check to reject events that leak through FSEvents overflow.
-// Matches /node_modules/, /.git/, /dist/, /build/, /.next/, etc. anywhere in path.
-const IGNORED_PATH_SEGMENTS_RE = /\/(?:node_modules|\.git|\.next|\.nuxt|__pycache__|coverage|\.gmax|\.venv|venv|site-packages|dist|build|out|target|vendor|\.tox|\.gradle|\.m2)\//;
 const DEBOUNCE_MS = 2000;
 const MAX_RETRIES = 5;
 const MAX_BATCH_SIZE = 50;
 class ProjectBatchProcessor {
     constructor(opts) {
+        var _a, _b;
         this.pending = new Map();
         this.retryCount = new Map();
+        this.retryAt = new Map();
+        this.terminalFailures = new Set();
         this.debounceTimer = null;
+        this.debounceDueMs = 0;
         this.activeBatch = null;
         this.processing = false;
         this.closed = false;
         this.currentBatchAc = null;
         this.lastCorruptionLogMs = 0;
+        this.policyChangedDuringBatch = false;
         this.projectRoot = opts.projectRoot;
         this.vectorDb = opts.vectorDb;
         this.metaCache = opts.metaCache;
+        this.workerPool = (_a = opts.workerPool) !== null && _a !== void 0 ? _a : (0, pool_1.getWorkerPool)();
         this.onReindex = opts.onReindex;
         this.onActivity = opts.onActivity;
+        this.onPolicyChange = opts.onPolicyChange;
+        this.onTerminalFailure = opts.onTerminalFailure;
+        this.onPathSuccess = opts.onPathSuccess;
+        this.runOperation = opts.runOperation;
+        this.filePolicy =
+            (_b = opts.filePolicy) !== null && _b !== void 0 ? _b : new file_policy_1.ProjectFilePolicy(opts.projectRoot);
         this.wtag = `watch:${path.basename(opts.projectRoot)}`;
         const taskTimeoutMs = (() => {
             var _a;
@@ -82,24 +90,38 @@ class ProjectBatchProcessor {
         this.batchTimeoutMs = Math.max(Math.ceil(taskTimeoutMs * 1.5), 120000);
     }
     handleFileEvent(event, absPath) {
-        var _a;
+        var _a, _b;
         if (this.closed)
             return;
-        const ext = path.extname(absPath).toLowerCase();
-        const bn = path.basename(absPath).toLowerCase();
-        if (!config_1.INDEXABLE_EXTENSIONS.has(ext) && !config_1.INDEXABLE_EXTENSIONS.has(bn))
+        const normalize = this.filePolicy.normalizeEventPath;
+        const normalized = normalize
+            ? normalize.call(this.filePolicy, absPath)
+            : this.filePolicy.isLexicallyContained(absPath)
+                ? path.resolve(absPath)
+                : null;
+        if (!normalized)
+            return;
+        if (this.filePolicy.isPolicyFile(normalized)) {
+            this.filePolicy.invalidateIgnoreCache();
+            if (this.processing)
+                this.policyChangedDuringBatch = true;
+            (_a = this.onPolicyChange) === null || _a === void 0 ? void 0 : _a.call(this);
             return;
-        // Safety net: reject paths with ignored directory segments.
-        // FSEvents can leak events during overflow before the watcher drops them.
-        if (IGNORED_PATH_SEGMENTS_RE.test(absPath))
+        }
+        if (!(0, file_utils_1.isIndexableFile)(normalized, 1) && !this.metaCache.get(normalized))
             return;
-        this.pending.set(absPath, event);
-        (_a = this.onActivity) === null || _a === void 0 ? void 0 : _a.call(this);
+        this.retryAt.delete(normalized);
+        this.pending.set(normalized, event);
+        (_b = this.onActivity) === null || _b === void 0 ? void 0 : _b.call(this);
         this.scheduleBatch();
     }
     /** Live (re)index progress: files queued + whether a batch is running. */
     get progress() {
-        return { pendingFiles: this.pending.size, processing: this.processing };
+        return {
+            pendingFiles: this.pending.size,
+            processing: this.processing,
+            failedFiles: this.terminalFailures.size,
+        };
     }
     close() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -109,24 +131,47 @@ class ProjectBatchProcessor {
             if (this.debounceTimer) {
                 clearTimeout(this.debounceTimer);
                 this.debounceTimer = null;
+                this.debounceDueMs = 0;
             }
             if (this.activeBatch) {
                 yield this.activeBatch;
             }
         });
     }
-    scheduleBatch() {
+    scheduleBatch(delayMs = DEBOUNCE_MS) {
+        const dueMs = Date.now() + Math.max(0, delayMs);
+        if (this.debounceTimer && this.debounceDueMs <= dueMs)
+            return;
         if (this.debounceTimer)
             clearTimeout(this.debounceTimer);
+        this.debounceDueMs = dueMs;
         this.debounceTimer = setTimeout(() => {
             this.debounceTimer = null;
+            this.debounceDueMs = 0;
             this.startBatch();
-        }, DEBOUNCE_MS);
+        }, Math.max(0, delayMs));
+    }
+    schedulePendingBatch(defaultDelayMs = DEBOUNCE_MS) {
+        var _a;
+        const now = Date.now();
+        let earliestRetryMs = Number.POSITIVE_INFINITY;
+        for (const absPath of this.pending.keys()) {
+            const retryAt = (_a = this.retryAt.get(absPath)) !== null && _a !== void 0 ? _a : 0;
+            if (retryAt <= now) {
+                this.scheduleBatch(defaultDelayMs);
+                return;
+            }
+            earliestRetryMs = Math.min(earliestRetryMs, retryAt - now);
+        }
+        this.scheduleBatch(Number.isFinite(earliestRetryMs) ? earliestRetryMs : defaultDelayMs);
     }
     startBatch() {
         if (this.activeBatch)
             return;
-        const run = this.processBatch().catch((err) => {
+        const execute = (signal) => this.processBatch(signal);
+        const run = (this.runOperation
+            ? this.runOperation(execute)
+            : execute(new AbortController().signal)).catch((err) => {
             console.error(`[${this.wtag}] Batch processing failed:`, err);
         });
         this.activeBatch = run;
@@ -135,9 +180,9 @@ class ProjectBatchProcessor {
                 this.activeBatch = null;
         });
     }
-    processBatch() {
+    processBatch(operationSignal) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a;
+            var _a, _b, _c, _d, _e;
             if (this.closed || this.processing || this.pending.size === 0)
                 return;
             // Circuit breaker: don't attempt writes when disk is critically low
@@ -145,29 +190,44 @@ class ProjectBatchProcessor {
                 (0, logger_1.log)(this.wtag, "Disk critically low — deferring batch processing");
                 if (this.debounceTimer)
                     clearTimeout(this.debounceTimer);
+                this.debounceDueMs = Date.now() + 60000;
                 this.debounceTimer = setTimeout(() => {
                     this.debounceTimer = null;
+                    this.debounceDueMs = 0;
                     this.startBatch();
                 }, 60000);
                 return;
             }
-            this.processing = true;
-            const batchAc = new AbortController();
-            this.currentBatchAc = batchAc;
-            const batchTimeout = setTimeout(() => {
-                (0, logger_1.log)(this.wtag, `Batch timed out after ${this.batchTimeoutMs}ms, aborting`);
-                batchAc.abort();
-            }, this.batchTimeoutMs);
             const batch = new Map();
+            const now = Date.now();
             let taken = 0;
             for (const [absPath, event] of this.pending) {
+                if (((_a = this.retryAt.get(absPath)) !== null && _a !== void 0 ? _a : 0) > now)
+                    continue;
                 batch.set(absPath, event);
                 taken++;
                 if (taken >= MAX_BATCH_SIZE)
                     break;
             }
+            if (batch.size === 0) {
+                this.schedulePendingBatch(30000);
+                return;
+            }
+            this.processing = true;
+            const batchAc = new AbortController();
+            const abortBatch = () => batchAc.abort(operationSignal.reason);
+            if (operationSignal.aborted)
+                abortBatch();
+            else
+                operationSignal.addEventListener("abort", abortBatch, { once: true });
+            this.currentBatchAc = batchAc;
+            const batchTimeout = setTimeout(() => {
+                (0, logger_1.log)(this.wtag, `Batch timed out after ${this.batchTimeoutMs}ms, aborting`);
+                batchAc.abort();
+            }, this.batchTimeoutMs);
             for (const key of batch.keys()) {
                 this.pending.delete(key);
+                this.retryAt.delete(key);
             }
             const filenames = [...batch.keys()].map((p) => path.basename(p));
             (0, logger_1.log)(this.wtag, `Processing ${batch.size} changed files: ${filenames.join(", ")}`);
@@ -177,12 +237,32 @@ class ProjectBatchProcessor {
             let backoffOverrideMs = 0;
             try {
                 // No lock needed — daemon is the single writer to LanceDB/MetaCache
-                const pool = (0, pool_1.getWorkerPool)();
+                const pool = this.workerPool;
                 const deletes = [];
                 const vectors = [];
                 const metaUpdates = new Map();
                 const metaDeletes = [];
                 const completed = new Set();
+                const retryFailures = new Set();
+                const requeuePath = (absPath, event, failed) => {
+                    var _a, _b;
+                    if (this.pending.has(absPath))
+                        return;
+                    if (failed) {
+                        const retry = (0, watcher_batch_1.computePathRetry)((_a = this.retryCount.get(absPath)) !== null && _a !== void 0 ? _a : 0, MAX_RETRIES, DEBOUNCE_MS);
+                        if (!retry.retry) {
+                            (0, logger_1.log)(this.wtag, `Dropped ${path.basename(absPath)} after ${MAX_RETRIES} retries`);
+                            this.retryCount.delete(absPath);
+                            this.retryAt.delete(absPath);
+                            this.terminalFailures.add(absPath);
+                            (_b = this.onTerminalFailure) === null || _b === void 0 ? void 0 : _b.call(this, absPath);
+                            return;
+                        }
+                        this.retryCount.set(absPath, retry.failures);
+                        this.retryAt.set(absPath, Date.now() + retry.backoffMs);
+                    }
+                    this.pending.set(absPath, event);
+                };
                 for (const [absPath, event] of batch) {
                     if (batchAc.signal.aborted)
                         break;
@@ -191,21 +271,18 @@ class ProjectBatchProcessor {
                         (processed % 10 === 0 || processed === batch.size)) {
                         (0, logger_1.log)(this.wtag, `Progress: ${processed}/${batch.size} (${reindexed} reindexed)`);
                     }
-                    if (event === "unlink") {
-                        deletes.push(absPath);
-                        metaDeletes.push(absPath);
-                        reindexed++;
-                        completed.add(absPath);
-                        continue;
-                    }
-                    // change or add
+                    // Reclassify every event at apply time. A catchup-derived unlink may be
+                    // stale if the file was recreated after its directory was scanned.
                     try {
-                        const stats = yield fs.promises.stat(absPath);
-                        if (!(0, file_utils_1.isIndexableFile)(absPath, stats.size)) {
-                            // File became non-indexable (emptied or now too large). If we
-                            // indexed it before, drop its chunks + meta so search stops
-                            // returning stale content; otherwise there's nothing to clean up.
-                            if (this.metaCache.get(absPath)) {
+                        const classification = yield this.filePolicy.classifyFile(absPath);
+                        if (classification.status === "error") {
+                            console.error(`[${this.wtag}] Policy could not classify ${absPath}:`, classification.error);
+                            retryFailures.add(absPath);
+                            continue;
+                        }
+                        if (classification.status === "excluded" ||
+                            classification.status === "missing") {
+                            if (event === "unlink" || this.metaCache.get(absPath)) {
                                 deletes.push(absPath);
                                 metaDeletes.push(absPath);
                                 reindexed++;
@@ -213,6 +290,7 @@ class ProjectBatchProcessor {
                             completed.add(absPath);
                             continue;
                         }
+                        const stats = classification.stat;
                         const cached = this.metaCache.get(absPath);
                         if ((0, cache_check_1.isFileCached)(cached, stats)) {
                             completed.add(absPath);
@@ -221,10 +299,16 @@ class ProjectBatchProcessor {
                         // Fast path: if only mtime changed but size matches and we have a hash,
                         // verify in-process instead of dispatching to a worker (~220ms saved).
                         if ((cached === null || cached === void 0 ? void 0 : cached.hash) && cached.size === stats.size) {
-                            const buf = yield fs.promises.readFile(absPath);
-                            const hash = (0, file_utils_1.computeContentHash)(buf, absPath);
+                            const snapshot = yield (0, file_utils_1.readFileSnapshot)(absPath, {
+                                projectRoot: this.projectRoot,
+                            });
+                            if (snapshot.size !== stats.size ||
+                                snapshot.mtimeMs !== stats.mtimeMs) {
+                                throw new Error("File changed after policy classification");
+                            }
+                            const hash = (0, file_utils_1.computeContentHash)(snapshot.buffer, absPath);
                             if (hash === cached.hash) {
-                                metaUpdates.set(absPath, Object.assign(Object.assign({}, cached), { mtimeMs: stats.mtimeMs }));
+                                metaUpdates.set(absPath, Object.assign(Object.assign({}, cached), { mtimeMs: snapshot.mtimeMs }));
                                 completed.add(absPath);
                                 continue;
                             }
@@ -232,7 +316,27 @@ class ProjectBatchProcessor {
                         const result = yield pool.processFile({
                             path: absPath,
                             absolutePath: absPath,
+                            projectRoot: this.projectRoot,
                         }, batchAc.signal);
+                        // Policy and filesystem state can change while embedding is in
+                        // flight. Never commit a result that no longer describes the path.
+                        const current = yield this.filePolicy.classifyFile(absPath);
+                        if (current.status === "error") {
+                            retryFailures.add(absPath);
+                            continue;
+                        }
+                        if (current.status === "excluded" || current.status === "missing") {
+                            deletes.push(absPath);
+                            metaDeletes.push(absPath);
+                            reindexed++;
+                            completed.add(absPath);
+                            continue;
+                        }
+                        if (current.stat.mtimeMs !== result.mtimeMs ||
+                            current.stat.size !== result.size) {
+                            retryFailures.add(absPath);
+                            continue;
+                        }
                         const metaEntry = {
                             hash: result.hash,
                             mtimeMs: result.mtimeMs,
@@ -274,15 +378,28 @@ class ProjectBatchProcessor {
                                 console.error(`[${this.wtag}] Worker pool unhealthy, aborting batch`);
                                 break;
                             }
-                            completed.add(absPath);
+                            retryFailures.add(absPath);
                         }
                     }
                 }
+                const pureDeleteCandidates = new Set(metaDeletes);
+                const authoritativeMetaDeletes = new Set();
+                for (const absPath of pureDeleteCandidates) {
+                    const current = yield this.filePolicy.classifyFile(absPath);
+                    if (current.status === "missing" || current.status === "excluded") {
+                        authoritativeMetaDeletes.add(absPath);
+                        continue;
+                    }
+                    completed.delete(absPath);
+                    batch.set(absPath, "change");
+                    if (current.status === "error")
+                        retryFailures.add(absPath);
+                }
                 // Requeue files that didn't reach a terminal outcome. This includes the
                 // file whose worker was in flight when the batch was aborted.
                 for (const [absPath, event] of batch) {
-                    if (!completed.has(absPath) && !this.pending.has(absPath)) {
-                        this.pending.set(absPath, event);
+                    if (!completed.has(absPath)) {
+                        requeuePath(absPath, event, retryFailures.has(absPath));
                     }
                 }
                 // Flush to VectorDB: insert first, then delete old (preserving new)
@@ -290,29 +407,44 @@ class ProjectBatchProcessor {
                 if (vectors.length > 0) {
                     yield this.vectorDb.insertBatch(vectors);
                 }
-                if (deletes.length > 0) {
+                for (const absPath of [...authoritativeMetaDeletes]) {
+                    const current = yield this.filePolicy.classifyFile(absPath);
+                    if (current.status === "missing" || current.status === "excluded") {
+                        continue;
+                    }
+                    authoritativeMetaDeletes.delete(absPath);
+                    completed.delete(absPath);
+                    batch.set(absPath, "change");
+                    requeuePath(absPath, "change", current.status === "error");
+                }
+                const deletesToApply = deletes.filter((absPath) => !pureDeleteCandidates.has(absPath) ||
+                    authoritativeMetaDeletes.has(absPath));
+                if (deletesToApply.length > 0) {
                     if (newIds.length > 0) {
-                        yield this.vectorDb.deletePathsExcludingIds(deletes, newIds);
+                        yield this.vectorDb.deletePathsExcludingIds(deletesToApply, newIds);
                     }
                     else {
-                        yield this.vectorDb.deletePaths(deletes);
+                        yield this.vectorDb.deletePaths(deletesToApply);
                     }
                 }
                 // Update MetaCache
                 for (const [p, entry] of metaUpdates) {
                     this.metaCache.put(p, entry);
                 }
-                for (const p of metaDeletes) {
+                for (const p of authoritativeMetaDeletes) {
                     this.metaCache.delete(p);
                 }
                 const duration = Date.now() - start;
                 if (reindexed > 0) {
-                    (_a = this.onReindex) === null || _a === void 0 ? void 0 : _a.call(this, reindexed, duration);
+                    (_b = this.onReindex) === null || _b === void 0 ? void 0 : _b.call(this, reindexed, duration);
                 }
                 const remaining = this.pending.size;
                 (0, logger_1.log)(this.wtag, `Batch complete: ${batch.size} files, ${reindexed} reindexed (${(duration / 1000).toFixed(1)}s)${remaining > 0 ? ` — ${remaining} remaining` : ""}`);
-                for (const absPath of batch.keys()) {
+                for (const absPath of completed) {
                     this.retryCount.delete(absPath);
+                    this.retryAt.delete(absPath);
+                    this.terminalFailures.delete(absPath);
+                    (_c = this.onPathSuccess) === null || _c === void 0 ? void 0 : _c.call(this, absPath);
                 }
                 // Trigger compaction if fragments are accumulating
                 if (reindexed > 0) {
@@ -328,6 +460,8 @@ class ProjectBatchProcessor {
                 // Disk pressure: requeue without counting as retries (not the file's fault)
                 if (err instanceof vector_db_1.DiskPressureError) {
                     for (const [absPath, event] of batch) {
+                        if (this.terminalFailures.has(absPath))
+                            continue;
                         if (!this.pending.has(absPath)) {
                             this.pending.set(absPath, event);
                         }
@@ -338,51 +472,81 @@ class ProjectBatchProcessor {
                 }
                 else if ((0, vector_db_1.isLanceCorruptionError)(err)) {
                     // Manifest references a missing fragment — retrying every 2s burns CPU
-                    // and floods logs without making progress. Log once per hour, drop the
-                    // batch (per-file retries would just re-fail), and back off 30 min so a
-                    // human can run `gmax index --reset` for the affected project.
+                    // and floods logs without making progress. Log once per hour, preserve
+                    // non-terminal events, and back off 30 min for manual recovery.
                     const now = Date.now();
                     if (now - this.lastCorruptionLogMs > 60 * 60 * 1000) {
                         this.lastCorruptionLogMs = now;
                         const msg = err instanceof Error ? err.message : String(err);
                         console.error(`[${this.wtag}] DATA CORRUPTION: LanceDB manifest references a missing fragment. ` +
                             `Backing off this project's batch processor for 30 min. ` +
-                            `To repair, run: gmax index --reset (in ${this.projectRoot}). Original: ${msg}`);
+                            `Preserve the store for diagnosis, then run 'gmax repair --rebuild' only when whole-corpus replacement is intended. Original: ${msg}`);
+                    }
+                    for (const [absPath, event] of batch) {
+                        if (this.terminalFailures.has(absPath))
+                            continue;
+                        if (!this.pending.has(absPath))
+                            this.pending.set(absPath, event);
                     }
-                    for (const [absPath] of batch)
-                        this.retryCount.delete(absPath);
                     backoffOverrideMs = 30 * 60 * 1000;
                 }
                 else {
                     console.error(`[${this.wtag}] Batch processing failed:`, err);
-                    const { requeued, dropped, backoffMs } = (0, watcher_batch_1.computeRetryAction)(batch, this.retryCount, MAX_RETRIES, false, 0, DEBOUNCE_MS);
-                    for (const [absPath, event] of requeued) {
-                        if (!this.pending.has(absPath)) {
-                            this.pending.set(absPath, event);
+                    let dropped = 0;
+                    const droppedPaths = [];
+                    for (const [absPath, event] of batch) {
+                        if (this.terminalFailures.has(absPath))
+                            continue;
+                        if (this.pending.has(absPath))
+                            continue;
+                        const retry = (0, watcher_batch_1.computePathRetry)((_d = this.retryCount.get(absPath)) !== null && _d !== void 0 ? _d : 0, MAX_RETRIES, DEBOUNCE_MS);
+                        if (!retry.retry) {
+                            this.retryCount.delete(absPath);
+                            this.retryAt.delete(absPath);
+                            this.terminalFailures.add(absPath);
+                            (_e = this.onTerminalFailure) === null || _e === void 0 ? void 0 : _e.call(this, absPath);
+                            dropped++;
+                            droppedPaths.push(absPath);
+                            continue;
                         }
+                        this.retryCount.set(absPath, retry.failures);
+                        this.retryAt.set(absPath, Date.now() + retry.backoffMs);
+                        this.pending.set(absPath, event);
                     }
                     if (dropped > 0) {
-                        const droppedPaths = [...batch.keys()].filter((p) => !requeued.has(p));
                         (0, logger_1.log)(this.wtag, `Dropped ${dropped} file(s) after ${MAX_RETRIES} retries: ${droppedPaths.map((p) => path.basename(p)).join(", ")}`);
                     }
-                    backoffOverrideMs = this.pending.size > 0 ? backoffMs : 0;
+                    backoffOverrideMs = 0;
                 }
             }
             finally {
                 clearTimeout(batchTimeout);
+                operationSignal.removeEventListener("abort", abortBatch);
                 this.currentBatchAc = null;
                 this.processing = false;
+                if (this.policyChangedDuringBatch) {
+                    this.policyChangedDuringBatch = false;
+                    for (const absPath of batch.keys()) {
+                        if (!this.pending.has(absPath)) {
+                            this.retryCount.delete(absPath);
+                            this.retryAt.delete(absPath);
+                            this.pending.set(absPath, "change");
+                        }
+                    }
+                }
                 if (!this.closed && this.pending.size > 0) {
                     if (backoffOverrideMs > 0) {
                         if (this.debounceTimer)
                             clearTimeout(this.debounceTimer);
+                        this.debounceDueMs = Date.now() + backoffOverrideMs;
                         this.debounceTimer = setTimeout(() => {
                             this.debounceTimer = null;
+                            this.debounceDueMs = 0;
                             this.startBatch();
                         }, backoffOverrideMs);
                     }
                     else {
-                        this.scheduleBatch();
+                        this.schedulePendingBatch();
                     }
                 }
             }

package/dist/lib/index/embedding-generation.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeEmbeddingFingerprint = computeEmbeddingFingerprint;
+exports.resolveEmbeddingGeneration = resolveEmbeddingGeneration;
+exports.parseEmbeddingGeneration = parseEmbeddingGeneration;
+exports.isOnnxFallbackCompatible = isOnnxFallbackCompatible;
+exports.compareEmbeddingGeneration = compareEmbeddingGeneration;
+const node_crypto_1 = require("node:crypto");
+const config_1 = require("../../config");
+function requireModelId(label, value) {
+    const normalized = value.trim();
+    if (!normalized)
+        throw new Error(`${label} must be a non-empty model ID`);
+    if (normalized !== value) {
+        throw new Error(`${label} must not contain surrounding whitespace`);
+    }
+    return value;
+}
+function computeEmbeddingFingerprint(identity) {
+    if (!Number.isInteger(identity.vectorDim) || identity.vectorDim <= 0) {
+        throw new Error("Embedding vector dimension must be a positive integer");
+    }
+    const canonical = [
+        "gmax-embedding-generation-v1",
+        requireModelId("Model tier", identity.tier),
+        identity.vectorDim,
+        requireModelId("ONNX model", identity.onnxModel),
+        requireModelId("MLX model", identity.mlxModel),
+        requireModelId("ColBERT model", identity.colbertModel),
+    ];
+    return (0, node_crypto_1.createHash)("sha256").update(JSON.stringify(canonical)).digest("hex");
+}
+function resolveEmbeddingGeneration(input) {
+    var _a;
+    const tier = config_1.MODEL_TIERS[input.modelTier];
+    if (!tier)
+        throw new Error(`Unknown model tier: ${input.modelTier}`);
+    if (input.vectorDim !== undefined && input.vectorDim !== tier.vectorDim) {
+        throw new Error(`Vector dimension ${input.vectorDim} contradicts model tier ${input.modelTier} (${tier.vectorDim})`);
+    }
+    const identity = {
+        tier: tier.id,
+        vectorDim: tier.vectorDim,
+        onnxModel: tier.onnxModel,
+        mlxModel: requireModelId("MLX model", (_a = input.mlxModel) !== null && _a !== void 0 ? _a : tier.mlxModel),
+        colbertModel: config_1.MODEL_IDS.colbert,
+    };
+    return Object.freeze(Object.assign(Object.assign({}, identity), { fingerprint: computeEmbeddingFingerprint(identity) }));
+}
+function parseEmbeddingGeneration(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Invalid embedding generation");
+    }
+    const candidate = value;
+    if (typeof candidate.tier !== "string" ||
+        typeof candidate.vectorDim !== "number" ||
+        typeof candidate.onnxModel !== "string" ||
+        typeof candidate.mlxModel !== "string" ||
+        typeof candidate.colbertModel !== "string" ||
+        typeof candidate.fingerprint !== "string") {
+        throw new Error("Invalid embedding generation");
+    }
+    const identity = {
+        tier: candidate.tier,
+        vectorDim: candidate.vectorDim,
+        onnxModel: candidate.onnxModel,
+        mlxModel: candidate.mlxModel,
+        colbertModel: candidate.colbertModel,
+    };
+    if (candidate.fingerprint !== computeEmbeddingFingerprint(identity)) {
+        throw new Error("Embedding generation identity is inconsistent");
+    }
+    return Object.freeze(Object.assign(Object.assign({}, identity), { fingerprint: candidate.fingerprint }));
+}
+function isOnnxFallbackCompatible(generation) {
+    const tier = config_1.MODEL_TIERS[generation.tier];
+    return ((tier === null || tier === void 0 ? void 0 : tier.id) === generation.tier &&
+        tier.vectorDim === generation.vectorDim &&
+        tier.onnxModel === generation.onnxModel &&
+        tier.mlxModel === generation.mlxModel);
+}
+function compareEmbeddingGeneration(persisted, configured) {
+    var _a;
+    const hasExactIdentity = persisted.embeddingFingerprint !== undefined &&
+        persisted.embedModel !== undefined &&
+        persisted.mlxModel !== undefined &&
+        persisted.colbertModel !== undefined;
+    const built = hasExactIdentity
+        ? parseEmbeddingGeneration({
+            tier: persisted.modelTier,
+            vectorDim: persisted.vectorDim,
+            onnxModel: persisted.embedModel,
+            mlxModel: persisted.mlxModel,
+            colbertModel: persisted.colbertModel,
+            fingerprint: persisted.embeddingFingerprint,
+        })
+        : resolveEmbeddingGeneration(Object.assign({ modelTier: persisted.modelTier, vectorDim: persisted.vectorDim }, (persisted.mlxModel === undefined
+            ? {}
+            : { mlxModel: persisted.mlxModel })));
+    return {
+        built,
+        state: ((_a = persisted.embeddingFingerprint) !== null && _a !== void 0 ? _a : built.fingerprint) !==
+            configured.fingerprint
+            ? "stale"
+            : persisted.embeddingFingerprint
+                ? "current"
+                : "legacy",
+    };
+}

package/dist/lib/index/embedding-status.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectEmbeddingStatus = projectEmbeddingStatus;
+exports.embeddingFingerprintLabel = embeddingFingerprintLabel;
+exports.assertEmbeddingSearchCompatible = assertEmbeddingSearchCompatible;
+const embedding_generation_1 = require("./embedding-generation");
+function projectEmbeddingStatus(project, config) {
+    const configured = (0, embedding_generation_1.resolveEmbeddingGeneration)(config);
+    if (!project || project.status !== "indexed") {
+        return { configured, built: null, state: "unbuilt" };
+    }
+    const comparison = (0, embedding_generation_1.compareEmbeddingGeneration)(project, configured);
+    return Object.assign({ configured }, comparison);
+}
+function embeddingFingerprintLabel(fingerprint) {
+    return fingerprint.slice(0, 12);
+}
+function assertEmbeddingSearchCompatible(projects, config) {
+    const stale = projects.filter((project) => projectEmbeddingStatus(project, config).state === "stale");
+    if (stale.length === 0)
+        return;
+    throw new Error(`embedding generation mismatch for ${stale.map((project) => project.name).join(", ")}; run gmax repair --rebuild to rebuild the whole corpus`);
+}