renor-engine 0.0.0-stage → 1.0.0

package/dist/embeddings/coalescing.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CoalescingEmbeddingProvider = exports.COALESCE_REQUESTS_IN_FLIGHT = exports.COALESCE_REQUEST_TEXTS = void 0;
+const types_1 = require("./types");
+/** Texts per request to the service: one predict call takes this many (the Vertex provider splits at the same size). */
+exports.COALESCE_REQUEST_TEXTS = 32;
+/** Requests in flight at once: the same as the rebuild's concurrency, so the service sees no more of them than before. */
+exports.COALESCE_REQUESTS_IN_FLIGHT = 4;
+/** How long a request waits for more callers when the queue is short and a request slot is free. */
+const GATHER_MS = 2;
+/**
+ * Batches the document embeddings of concurrent callers into shared requests.
+ *
+ * An index pass embeds one note at a time, a request of three or four texts, so a pass over N notes waited on about N
+ * round trips. This provider takes the texts of every caller that is waiting, in arrival order, and sends them as one
+ * request of up to COALESCE_REQUEST_TEXTS texts, with at most COALESCE_REQUESTS_IN_FLIGHT requests out at once. Each caller
+ * gets back exactly the vectors of its own texts, in its own order, so what it stores is what it would have stored alone.
+ *
+ * Failures stay per caller. A caller that stops waiting (its budget ran out, or its signal aborted) is dropped from the queue,
+ * or from the request if it is already out, and the request is aborted once no caller of it still waits. When a request
+ * fails for a reason other than the service being unavailable (a text it refuses, say), each of its callers is sent again
+ * alone, as it would have been without batching, so one refused text fails one note and no other.
+ *
+ * Queries do not wait for a batch: `embedQuery` goes straight to the provider.
+ */
+class CoalescingEmbeddingProvider {
+    dimensions;
+    identity;
+    inner;
+    queue = [];
+    inFlight = 0;
+    gatherTimer;
+    gatherDone = false;
+    constructor(inner) {
+        this.inner = inner;
+        this.dimensions = inner.dimensions;
+        this.identity = inner.identity;
+    }
+    embed(texts, options) {
+        if (texts.length === 0)
+            return Promise.resolve([]);
+        // An abort that came first is never heard as an event, so it is checked here.
+        if (options?.signal?.aborted)
+            return Promise.reject(options.signal.reason);
+        return new Promise((resolve, reject) => {
+            const caller = { texts, options, resolve, reject, done: false };
+            options?.signal?.addEventListener('abort', () => this.abandon(caller, options.signal.reason), { once: true });
+            this.queue.push(caller);
+            this.schedule();
+        });
+    }
+    embedQuery(text, options) {
+        return this.inner.embedQuery
+            ? this.inner.embedQuery(text, options)
+            : this.inner.embed([text], options).then(vectors => vectors[0]);
+    }
+    describe() {
+        return this.inner.describe?.() ?? {};
+    }
+    /** A caller that stopped waiting: out of the queue if it has not gone yet, otherwise its request runs on for the others. */
+    abandon(caller, reason) {
+        if (caller.done)
+            return;
+        caller.done = true;
+        this.queue = this.queue.filter(c => c !== caller);
+        caller.reject(reason);
+        this.schedule();
+    }
+    schedule() {
+        while (this.inFlight < exports.COALESCE_REQUESTS_IN_FLIGHT && this.queue.length > 0) {
+            const queued = this.queue.reduce((sum, c) => sum + c.texts.length, 0);
+            if (queued < exports.COALESCE_REQUEST_TEXTS && !this.gatherDone) {
+                this.gatherTimer ??= setTimeout(() => {
+                    this.gatherTimer = undefined;
+                    this.gatherDone = true;
+                    this.schedule();
+                }, GATHER_MS);
+                return;
+            }
+            const batch = [];
+            let size = 0;
+            // A request is either all interactive (each caller may abort it) or all patient: a patient caller would keep an
+            // interactive caller's request alive after that caller gave up, and its retries would reach a refusing service.
+            while (this.queue.length > 0 && (batch.length === 0 || (sameKind(this.queue[0], batch[0])
+                && size + this.queue[0].texts.length <= exports.COALESCE_REQUEST_TEXTS))) {
+                const caller = this.queue.shift();
+                batch.push(caller);
+                size += caller.texts.length;
+            }
+            this.gatherDone = false;
+            this.inFlight += 1;
+            this.send(batch);
+        }
+    }
+    send(batch) {
+        const texts = batch.flatMap(c => c.texts);
+        const controller = new AbortController();
+        const budgets = batch.map(c => c.options?.budgetMs);
+        const budgetMs = budgets.some(b => b === undefined) ? undefined : Math.max(...budgets);
+        // A caller without a signal waits as long as the service takes: the request then runs to its end.
+        let waiting = batch.length;
+        const patient = batch.some(c => c.options?.signal === undefined);
+        for (const caller of batch) {
+            const signal = caller.options?.signal;
+            if (!signal)
+                continue;
+            signal.addEventListener('abort', () => {
+                waiting -= 1;
+                if (waiting === 0 && !patient)
+                    controller.abort(signal.reason);
+            }, { once: true });
+        }
+        const request = this.inner.embed(texts, { budgetMs, signal: controller.signal });
+        request.then((vectors) => {
+            this.inFlight -= 1;
+            let offset = 0;
+            for (const caller of batch) {
+                const own = vectors.slice(offset, offset + caller.texts.length);
+                offset += caller.texts.length;
+                if (caller.done)
+                    continue;
+                caller.done = true;
+                if (own.length === caller.texts.length)
+                    caller.resolve(own);
+                else
+                    caller.reject(new Error(`the embedding provider returned ${own.length} vectors for ${caller.texts.length} texts`));
+            }
+            this.schedule();
+        }, (err) => {
+            this.inFlight -= 1;
+            this.schedule();
+            if (isUnavailable(err) || controller.signal.aborted) {
+                for (const caller of batch) {
+                    if (caller.done)
+                        continue;
+                    caller.done = true;
+                    caller.reject(err);
+                }
+                return;
+            }
+            // A 400 names an input the service refuses: each caller goes again alone, so the others are not failed by it.
+            // Any other refusal is the service's answer to the request, and every caller of it gets that answer (no re-sends).
+            if (!refusesAnInput(err)) {
+                for (const caller of batch) {
+                    if (caller.done)
+                        continue;
+                    caller.done = true;
+                    caller.reject(err);
+                }
+                return;
+            }
+            for (const caller of batch) {
+                if (caller.done)
+                    continue;
+                this.inner.embed(caller.texts, caller.options).then((vectors) => { if (!caller.done) {
+                    caller.done = true;
+                    caller.resolve(vectors);
+                } }, (own) => { if (!caller.done) {
+                    caller.done = true;
+                    caller.reject(own);
+                } });
+            }
+        });
+    }
+}
+exports.CoalescingEmbeddingProvider = CoalescingEmbeddingProvider;
+/** The service did not answer (or the call was cut off): every caller of the request meets the same answer, as each would alone. */
+function isUnavailable(err) {
+    return err instanceof types_1.EmbeddingUnavailableError || (err instanceof Error && err.name === 'AbortError');
+}
+/** The service refused an input (HTTP 400), not the request as a whole: the callers of the request are sent again one by one. */
+function refusesAnInput(err) {
+    return err instanceof Error && err.status === 400;
+}
+function sameKind(a, b) {
+    return (a.options?.signal !== undefined) === (b.options?.signal !== undefined);
+}

package/dist/embeddings/interactive.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InteractiveEmbeddingProvider = void 0;
+const types_1 = require("./types");
+/**
+ * An embedding provider for a service an agent waits on.
+ *
+ * A call without a budget is passed straight through: patient, the provider's own retries, for a rebuild, a backfill or
+ * a benchmark. A call with `budgetMs` is interactive: it ends within the budget, with `EmbeddingUnavailableError`, when
+ * the service is slow, refusing or silent. Google's 429s on 2026-10-06 made `remember` wait up to 13 minutes in the
+ * provider's retry loop while holding the note's file lock, which every later save and read of that note queued behind.
+ *
+ * It also remembers that the service just failed. After an interactive call fails because the service is unavailable,
+ * interactive calls fail at once for `cooldownMs` without asking it, so a refusing service costs one call a few
+ * seconds and every other call nothing; the first call after the cooldown is the probe, and one that succeeds (or a
+ * patient call that does) opens the way again. A failure that is not an outage (a text the service refuses) does not
+ * close it: it says nothing about the next call.
+ */
+class InteractiveEmbeddingProvider {
+    dimensions;
+    identity;
+    inner;
+    cooldownMs;
+    /** Epoch ms before which interactive calls are not made; 0 when the service is believed up. */
+    unavailableUntil = 0;
+    /** An interactive call is the probe after a cooldown: the others wait for its verdict instead of piling on. */
+    probing = false;
+    constructor(inner, options = {}) {
+        this.inner = inner;
+        this.dimensions = inner.dimensions;
+        this.identity = inner.identity;
+        this.cooldownMs = options.cooldownMs ?? DEFAULT_COOLDOWN_MS;
+    }
+    embed(texts, options) {
+        return this.run(options, o => this.inner.embed(texts, o));
+    }
+    embedQuery(text, options) {
+        return this.run(options, async (o) => this.inner.embedQuery ? this.inner.embedQuery(text, o) : (await this.inner.embed([text], o))[0]);
+    }
+    describe() {
+        return this.inner.describe?.() ?? {};
+    }
+    async run(options, call) {
+        const budgetMs = options?.budgetMs;
+        if (budgetMs === undefined) {
+            // Patient: never refused, and what it learns about the service is passed on.
+            try {
+                const result = await call(options);
+                this.unavailableUntil = 0;
+                return result;
+            }
+            catch (err) {
+                if (err instanceof types_1.EmbeddingUnavailableError)
+                    this.unavailableUntil = Date.now() + this.cooldownMs;
+                throw err;
+            }
+        }
+        if (Date.now() < this.unavailableUntil || (this.probing && this.unavailableUntil > 0)) {
+            throw new types_1.EmbeddingUnavailableError('embedding service unavailable (failed moments ago; not asked again yet)');
+        }
+        const probe = this.unavailableUntil > 0;
+        if (probe)
+            this.probing = true;
+        const controller = new AbortController();
+        const relay = () => controller.abort(options?.signal?.reason);
+        options?.signal?.addEventListener('abort', relay, { once: true });
+        let timer;
+        const expired = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                const unavailable = new types_1.EmbeddingUnavailableError(`embedding service did not answer within ${Math.ceil(budgetMs / 1000)} s`);
+                // The provider is told to stop (a provider that honours the signal ends its retries and its request); one
+                // that does not is left to finish unobserved, and its late answer or failure is dropped.
+                controller.abort(unavailable);
+                reject(unavailable);
+            }, budgetMs);
+        });
+        try {
+            const attempt = call({ ...options, signal: controller.signal });
+            attempt.catch(() => undefined); // an attempt that loses the race settles later; nobody reads it
+            const result = await Promise.race([attempt, expired]);
+            this.unavailableUntil = 0;
+            return result;
+        }
+        catch (err) {
+            // An abort reaches a provider as an AbortError or as the reason it was given; either way it is the budget's.
+            const unavailable = controller.signal.aborted && controller.signal.reason instanceof types_1.EmbeddingUnavailableError
+                ? controller.signal.reason
+                : err;
+            if (unavailable instanceof types_1.EmbeddingUnavailableError)
+                this.unavailableUntil = Date.now() + this.cooldownMs;
+            throw unavailable;
+        }
+        finally {
+            clearTimeout(timer);
+            options?.signal?.removeEventListener('abort', relay);
+            if (probe)
+                this.probing = false;
+        }
+    }
+}
+exports.InteractiveEmbeddingProvider = InteractiveEmbeddingProvider;
+/** Long enough that a refusing service is not asked by every call, short enough that a recovered one is used again at once. */
+const DEFAULT_COOLDOWN_MS = 15_000;

package/dist/embeddings/local.js

@@ -0,0 +1,68 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalEmbeddingProvider = void 0;
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+// Models that require asymmetric query/passage prefixes
+const E5_PREFIX_MODELS = ['multilingual-e5', 'e5-'];
+function needsE5Prefix(modelName) {
+    return E5_PREFIX_MODELS.some(p => modelName.toLowerCase().includes(p));
+}
+// Dimension map for known models
+const MODEL_DIMENSIONS = {
+    'Xenova/all-MiniLM-L6-v2': 384,
+    'Xenova/multilingual-e5-small': 384,
+    'Xenova/multilingual-e5-base': 768,
+    'Xenova/multilingual-e5-large': 1024,
+    'intfloat/multilingual-e5-base': 768,
+};
+class LocalEmbeddingProvider {
+    dimensions;
+    identity;
+    modelName;
+    extractor = null;
+    initPromise = null;
+    constructor(modelName) {
+        this.modelName = modelName ?? 'Xenova/multilingual-e5-base';
+        this.dimensions = MODEL_DIMENSIONS[this.modelName] ?? 768;
+        this.identity = { kind: 'local', model: this.modelName };
+    }
+    getExtractor() {
+        if (this.extractor)
+            return Promise.resolve(this.extractor);
+        if (this.initPromise)
+            return this.initPromise;
+        this.initPromise = (async () => {
+            // An optional peer dependency: an `npx renor-engine` install leaves it out (it is hundreds of megabytes), a clone has it.
+            const { pipeline, env } = await import('@xenova/transformers').catch((err) => {
+                if (!/cannot find (module|package)/i.test(String(err?.message)))
+                    throw err;
+                throw new Error('EMBEDDING_PROVIDER=local needs the optional package @xenova/transformers: add it (`npx -y -p renor-engine -p @xenova/transformers renor-engine mcp`, or `npm install @xenova/transformers` beside a clone) or set EMBEDDING_PROVIDER=none');
+            });
+            env.cacheDir = path_1.default.join(os_1.default.homedir(), '.cache', 'osm-memory', 'models');
+            this.extractor = await pipeline('feature-extraction', this.modelName);
+            return this.extractor;
+        })();
+        return this.initPromise;
+    }
+    async embed(texts) {
+        if (texts.length === 0)
+            return [];
+        const extractor = await this.getExtractor();
+        const prefixed = needsE5Prefix(this.modelName)
+            ? texts.map(t => `passage: ${t}`)
+            : texts;
+        const output = await extractor(prefixed, { pooling: 'mean', normalize: true });
+        return output.tolist();
+    }
+    async embedQuery(text) {
+        const extractor = await this.getExtractor();
+        const prefixed = needsE5Prefix(this.modelName) ? `query: ${text}` : text;
+        const output = await extractor([prefixed], { pooling: 'mean', normalize: true });
+        return output.tolist()[0];
+    }
+}
+exports.LocalEmbeddingProvider = LocalEmbeddingProvider;

package/dist/embeddings/openai.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAIEmbeddingProvider = void 0;
+/**
+ * Generic OpenAI-compatible embeddings provider.
+ * Works with OpenAI, Voyage AI (voyageai.com, OpenAI-shaped /v1/embeddings),
+ * and any compatible gateway. Configured via EMBEDDING_BASE_URL and
+ * EMBEDDING_DIMS (defaults preserve upstream OpenAI behavior).
+ *
+ * The `openai` SDK is required in the constructor rather than imported: it costs
+ * ~70 ms to load, it is reached on every cold start of dist/mvp/cli.js through
+ * this module, and a workspace only ever constructs this class when its
+ * embedding provider IS openai. A workspace on Vertex (every provisioned
+ * workspace) or on no provider never constructs it, so for those the SDK was
+ * ~70 ms of a wake that could not use it. The import above is `import type`, so
+ * it is erased at compile time and contributes nothing at load — the type stays
+ * checked, the module is not loaded.
+ */
+class OpenAIEmbeddingProvider {
+    dimensions;
+    identity;
+    /** The dims the user explicitly configured (EMBEDDING_DIMS); null = SDK/gateway default. */
+    configuredDims;
+    clients = [];
+    cooldown = new Map();
+    rr = 0;
+    model;
+    constructor(apiKeys, model, baseURL, dimensions) {
+        const keys = Array.isArray(apiKeys) ? apiKeys.filter(Boolean) : [apiKeys];
+        if (keys.length === 0)
+            throw new Error('at least one API key required');
+        this.model = model ?? 'text-embedding-3-small';
+        this.identity = { kind: 'openai', model: this.model };
+        this.configuredDims = dimensions ?? null;
+        this.dimensions = dimensions ?? 1536;
+        // CommonJS loader, deferred: this is the only line that actually pulls the SDK.
+        const OpenAICtor = require('openai').default;
+        this.clients = keys.map(apiKey => new OpenAICtor({ apiKey, baseURL }));
+    }
+    /** next healthy client index (round-robin over non-cooling keys) */
+    nextClient() {
+        const now = Date.now();
+        for (let t = 0; t < this.clients.length; t++) {
+            const i = (this.rr + t) % this.clients.length;
+            if ((this.cooldown.get(i) ?? 0) <= now) {
+                this.rr = i + 1;
+                return i;
+            }
+        }
+        return -1; // all cooling
+    }
+    async embed(texts) {
+        const results = [];
+        const rawBatchSize = process.env.EMBEDDING_BATCH_SIZE;
+        const batchSize = rawBatchSize === undefined ? 32 : Number(rawBatchSize);
+        if (!Number.isInteger(batchSize) || batchSize <= 0) {
+            throw new Error('EMBEDDING_BATCH_SIZE must be a positive integer');
+        }
+        for (let i = 0; i < texts.length; i += batchSize) {
+            const batch = texts.slice(i, i + batchSize);
+            results.push(...(await this.embedWithRetry(batch)));
+        }
+        return results;
+    }
+    /** Retries on 429/5xx with exponential backoff; on 429 rotates to the next healthy key first. */
+    async embedWithRetry(batch, attempt = 0) {
+        const ci = this.nextClient();
+        if (ci === -1) {
+            const waitMs = Math.max(2000, 1000 * 2 ** Math.min(attempt, 8));
+            await new Promise(r => setTimeout(r, waitMs));
+            return this.embedWithRetry(batch, attempt + 1);
+        }
+        try {
+            // Product defect fix (P1, disclosed): when EMBEDDING_DIMS is configured it
+            // sizes the vector index table — it MUST also be sent to the gateway, or
+            // gateways whose omission default differs (e.g. Google: 3072) return
+            // mismatched vectors and indexing fails. Unconfigured callers keep the
+            // previous behavior (SDK/gateway default).
+            const res = await this.clients[ci].embeddings.create(this.configuredDims !== null
+                ? { model: this.model, input: batch, dimensions: this.configuredDims }
+                : { model: this.model, input: batch });
+            return res.data.map(d => d.embedding);
+        }
+        catch (e) {
+            const status = e?.status;
+            if (status === 429 && attempt < 40) {
+                this.cooldown.set(ci, Date.now() + 60_000);
+                return this.embedWithRetry(batch, attempt + 1); // immediate retry on another key
+            }
+            if (status === 401 || status === 403) {
+                this.cooldown.set(ci, Number.MAX_SAFE_INTEGER); // dead key — never use again this run
+                if (attempt < 40)
+                    return this.embedWithRetry(batch, attempt + 1);
+                throw e;
+            }
+            if (status >= 500 && status < 600 && attempt < 10) {
+                const waitMs = Math.max(Number(e?.headers?.get?.('retry-after')) * 1000 || 0, 1000 * 2 ** attempt, 2000);
+                await new Promise(r => setTimeout(r, waitMs));
+                return this.embedWithRetry(batch, attempt + 1);
+            }
+            throw e;
+        }
+    }
+}
+exports.OpenAIEmbeddingProvider = OpenAIEmbeddingProvider;

package/dist/embeddings/rebuild.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chunksWithoutVectors = chunksWithoutVectors;
+exports.sleep = sleep;
+exports.rebuildEmbeddings = rebuildEmbeddings;
+exports.embedMissingVectors = embedMissingVectors;
+const ATTEMPTS = 3;
+/** How many chunks have no stored vector (vec0's rowid shadow table holds one row per stored vector). */
+function chunksWithoutVectors(db) {
+    return db.prepare('SELECT COUNT(*) FROM chunks c WHERE NOT EXISTS (SELECT 1 FROM chunk_embeddings_rowids r WHERE r.rowid = c.id)').pluck().get();
+}
+/** Wait `ms`, or less if `signal` aborts. The timer never keeps the process alive. */
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (ms <= 0 || signal?.aborted)
+            return resolve();
+        const done = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        timer.unref();
+        signal?.addEventListener('abort', done, { once: true });
+    });
+}
+/**
+ * Rebuild (or carry on rebuilding) the vectors of `vectors` in `space`, the space `provider` writes. Returns when the
+ * index is whole, or when `options.signal` aborts. The index is marked whole only when no chunk is left without a
+ * vector: a chunk the provider will not embed (a text it refuses, or a provider that is down) makes this throw, after
+ * every other chunk is embedded, and the index stays unfinished for a later call to resume, so semantic search is
+ * never turned on over an index with a vector missing. A save that changes chunks meanwhile is safe: a vector is
+ * stored only for a chunk that is still as it was when it was read, and the save embeds its own.
+ */
+async function rebuildEmbeddings(db, vectors, provider, space, options = {}) {
+    const { batchSize = 32, concurrency = 4, signal, retryDelayMs = (attempt) => 1_000 * 4 ** attempt, } = options;
+    // An index in another space, or in none that anyone can vouch for, starts over; one in this space that is
+    // unfinished carries on; one that is whole has nothing to do.
+    if (vectors.space() !== space)
+        vectors.beginRebuild(space);
+    else if (!vectors.rebuilding())
+        return { done: true, embedded: 0 };
+    // The chunks that still have no vector. Nothing is ever passed over: a chunk is stored, or it is gone (a save
+    // replaced it), or this call throws; so the scan is over exactly when no chunk lacks a vector.
+    const nextRows = db.prepare(`SELECT c.id, c.text FROM chunks c
+     WHERE NOT EXISTS (SELECT 1 FROM chunk_embeddings_rowids r WHERE r.rowid = c.id)
+     ORDER BY c.id LIMIT ?`);
+    const stillThere = db.prepare('SELECT 1 FROM chunks WHERE id = ? AND text = ?');
+    const noteOf = db.prepare('SELECT note_path FROM chunks WHERE id = ?').pluck();
+    // Vectors whose chunk is gone: a process with no embedding provider replaces chunks and cannot delete their vectors.
+    const orphans = db.prepare('SELECT r.rowid FROM chunk_embeddings_rowids r WHERE NOT EXISTS (SELECT 1 FROM chunks c WHERE c.id = r.rowid)').pluck();
+    const result = { done: false, embedded: 0 };
+    /** One request: embed these chunks, and keep the vector of each that is still as it was read. */
+    const embedAndStore = async (rows) => {
+        const embeddings = await provider.embed(rows.map((r) => r.text));
+        if (embeddings.length !== rows.length) {
+            throw new Error(`the embedding provider returned ${embeddings.length} vectors for ${rows.length} texts`);
+        }
+        db.transaction(() => {
+            rows.forEach((row, i) => {
+                // A save may have replaced this chunk meanwhile; it embedded its own.
+                if (stillThere.get(row.id, row.text))
+                    vectors.upsert(row.id, embeddings[i]);
+            });
+        })();
+        result.embedded += rows.length;
+    };
+    /** Try to embed `rows` (up to ATTEMPTS times); the last error, or null once they are stored. */
+    const attempt = async (rows) => {
+        let failure = null;
+        for (let tries = 0; tries < ATTEMPTS && !signal?.aborted; tries++) {
+            try {
+                await embedAndStore(rows);
+                return null;
+            }
+            catch (err) {
+                failure = err;
+                if (tries + 1 < ATTEMPTS)
+                    await sleep(retryDelayMs(tries), signal);
+            }
+        }
+        return failure;
+    };
+    /**
+     * Embed `rows`. When a batch keeps failing, embed its chunks one by one, so that every chunk the provider takes is
+     * stored and only the ones it refuses stay behind; then throw, naming the first. Nothing is skipped.
+     */
+    const settle = async (rows) => {
+        const failure = await attempt(rows);
+        if (failure === null || signal?.aborted)
+            return;
+        let refused;
+        if (rows.length === 1)
+            refused = { row: rows[0], failure };
+        else {
+            for (const row of rows) {
+                const one = await attempt([row]);
+                if (signal?.aborted)
+                    return;
+                if (one !== null)
+                    refused ??= { row, failure: one };
+            }
+        }
+        if (!refused)
+            return;
+        const note = noteOf.get(refused.row.id);
+        const why = refused.failure instanceof Error ? refused.failure.message : String(refused.failure);
+        throw Object.assign(new Error(`chunk ${refused.row.id}${note ? ` of ${note}` : ''} could not be embedded: ${why}`), { cause: refused.failure });
+    };
+    while (!signal?.aborted) {
+        const rows = nextRows.all(batchSize * concurrency);
+        if (rows.length === 0) {
+            // Whole: every chunk has its vector, and the vectors of chunks that are gone are dropped with the mark.
+            db.transaction(() => {
+                for (const id of orphans.all())
+                    vectors.delete(id);
+                vectors.finishRebuild();
+            })();
+            return { ...result, done: true };
+        }
+        const groups = [];
+        for (let i = 0; i < rows.length; i += batchSize)
+            groups.push(rows.slice(i, i + batchSize));
+        // Every request settles before this call returns or throws, so nothing is left running against the database.
+        const settled = await Promise.allSettled(groups.map(settle));
+        const failed = settled.find((s) => s.status === 'rejected');
+        if (failed)
+            throw failed.reason;
+    }
+    return result;
+}
+/**
+ * Embed every chunk that has no vector, a batch at a time, until none is left or `signal` aborts: the chunks a save
+ * kept for keyword search because the embedding service would not answer it in time. It is the patient half of an
+ * interactive save: it waits as long as the provider's own retries take, and holds no lock while it does, so a service
+ * that is down costs nothing but this task's time. A vector is stored only for a chunk that is still as it was read (a
+ * save may have replaced it meanwhile and embedded its own). Throws what the provider throws, after which a later call
+ * carries on with what is left; it does not change what the index says of its own completeness (a rebuild does that).
+ * Returns how many chunks it embedded.
+ */
+async function embedMissingVectors(db, vectors, provider, options = {}) {
+    const { batchSize = 32, signal } = options;
+    const nextRows = db.prepare(`SELECT c.id, c.text FROM chunks c
+     WHERE NOT EXISTS (SELECT 1 FROM chunk_embeddings_rowids r WHERE r.rowid = c.id)
+     ORDER BY c.id LIMIT ?`);
+    const stillThere = db.prepare('SELECT 1 FROM chunks WHERE id = ? AND text = ?');
+    const embedOptions = signal ? { signal } : undefined;
+    let embedded = 0;
+    while (!signal?.aborted) {
+        const rows = nextRows.all(batchSize);
+        if (rows.length === 0)
+            break;
+        const embeddings = await provider.embed(rows.map((r) => r.text), embedOptions);
+        if (embeddings.length !== rows.length) {
+            throw new Error(`the embedding provider returned ${embeddings.length} vectors for ${rows.length} texts`);
+        }
+        db.transaction(() => {
+            rows.forEach((row, i) => {
+                if (stillThere.get(row.id, row.text))
+                    vectors.upsert(row.id, embeddings[i]);
+            });
+        })();
+        embedded += rows.length;
+    }
+    return embedded;
+}