akm-cli 0.9.16-alpha.1 → 0.9.16-alpha.2

package/dist/indexer/drain.js

@@ -1,306 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { getConfigPath } from "../core/paths.js";
-import { isVerbose } from "../core/warn.js";
-import { embedBatch } from "../llm/embedder.js";
-import { probeProviderLimits } from "../llm/embedders/provider-limits.js";
-import { describeEmbeddingCredential, hasRemoteEndpoint, normalizeEmbeddingEndpoint, } from "../llm/embedders/remote.js";
-import { getMeta, setMeta } from "../storage/repositories/index-meta-repository.js";
-import { SQLITE_CHUNK_SIZE } from "../storage/repositories/index-sql.js";
-import { isVecAvailable } from "../storage/repositories/index-vec-repository.js";
-import { dropOtherIdentities, listMissingHashes, upsertUnitVectors } from "../storage/repositories/units-repository.js";
-import { deriveObservedEmbeddingIdentity } from "./embedding-identity.js";
-/**
- * Failure threshold, within the recent window below, that stops dispatching
- * further provider batches. Mirrors materialize-embeddings.ts's own
- * (unexported) `CIRCUIT_BREAKER_THRESHOLD`, #954 — reimplemented here at the
- * same value rather than imported, since that file is private and slated for
- * deletion by B5; the underlying stop-dispatch MECHANISM (`onSkip` returning
- * `false`) is still the real `RemoteEmbedder`'s, reused unmodified. Two
- * independent streaks share it: single-document failures (a multi-document
- * timeout is not yet evidence of a dead endpoint — `RemoteEmbedder` retries
- * and splits it smaller before ever reporting it this small), or network
- * errors at ANY size (never retried, trusted immediately). Storage-write
- * failures (E5b — `upsertUnitVectors`'s own per-row result) feed the SAME two
- * streaks: a sustained STORAGE failure (contention, permissions, a full
- * disk) must stop paying for provider requests just as surely as a
- * sustained PROVIDER failure, even while the provider itself keeps
- * succeeding.
- */
-const CIRCUIT_BREAKER_THRESHOLD = 3;
-/**
- * Recent-history window (in settled batch-starts) the two streaks above are
- * evaluated over, in place of a plain "reset to zero on any success" counter
- * (round-2 field finding): with concurrent dispatch (default 2, up to 16)
- * outcomes settle out of dispatch order, so a degraded endpoint failing MOST
- * requests never tripped the breaker as long as occasional successes
- * interleaved — reproduced with a 67% failure rate dispatching the entire
- * pending set. `CIRCUIT_BREAKER_THRESHOLD` failures within the last
- * `CIRCUIT_BREAKER_WINDOW` settled batch-starts of a streak's own kind (see
- * {@link pushBreakerOutcome}) trips it: a genuinely dead endpoint (no
- * successes at all) still trips in exactly `CIRCUIT_BREAKER_THRESHOLD`
- * batches, same as before; a single success now only AGES a failure out of
- * the window over time rather than erasing the whole run's evidence at once.
- */
-const CIRCUIT_BREAKER_WINDOW = CIRCUIT_BREAKER_THRESHOLD * 2;
-/** Record one settled batch-start's outcome into a breaker streak's window, capped at {@link CIRCUIT_BREAKER_WINDOW}. */
-function pushBreakerOutcome(window, isFailure) {
-    window.push(isFailure);
-    if (window.length > CIRCUIT_BREAKER_WINDOW)
-        window.shift();
-}
-/** Failures currently recorded in a breaker streak's window. */
-function breakerFailureCount(window) {
-    return window.reduce((n, isFailure) => n + (isFailure ? 1 : 0), 0);
-}
-/**
- * Prefix of the per-committed-batch progress line (`"${DRAIN_BATCH_PROGRESS_PREFIX}N: …"`,
- * emitted once per provider batch this call commits). Exported so a caller
- * juggling several `onProgress` sources (`stash-cli.ts`'s `akm index`) can
- * recognize — and, outside `--verbose`, suppress — this specific
- * high-frequency line by prefix rather than re-deriving its own copy of the
- * pattern (#954).
- */
-export const DRAIN_BATCH_PROGRESS_PREFIX = "[drain] batch ";
-function throwIfAborted(signal) {
-    if (signal?.aborted) {
-        throw signal.reason instanceof Error ? signal.reason : new Error("drain interrupted");
-    }
-}
-/** Every distinct unit hash the index currently knows about, regardless of identity. */
-function selectAllUnitHashes(db) {
-    return db.prepare("SELECT unit_hash FROM unit_texts ORDER BY unit_hash").all().map((row) => row.unit_hash);
-}
-/** `unit_hash -> text` for exactly `hashes`, chunked to respect SQLite's bound-parameter limit. */
-function fetchUnitTexts(db, hashes) {
-    const texts = new Map();
-    for (let offset = 0; offset < hashes.length; offset += SQLITE_CHUNK_SIZE) {
-        const chunk = hashes.slice(offset, offset + SQLITE_CHUNK_SIZE);
-        const placeholders = chunk.map(() => "?").join(",");
-        const rows = db
-            .prepare(`SELECT unit_hash, text FROM unit_texts WHERE unit_hash IN (${placeholders})`)
-            .all(...chunk);
-        for (const row of rows)
-            texts.set(row.unit_hash, row.text);
-    }
-    return texts;
-}
-/**
- * Effective embedding config and request packing for this drain (index
- * redesign, B5 — replaces the retired `embedding.maxTokens`/`batchSize`/
- * `contextLength` config keys): `concurrency` (in-flight requests) defaults
- * to the provider's OWN observed slot count when `embedding.concurrency`
- * itself leaves it unset (`probeProviderLimits` already applies that same
- * override to `slots`). The request TOKEN WINDOW, chars-per-token ratio, and
- * Ollama `num_ctx` are no longer config fields at all — they are threaded
- * into `RemoteEmbedder.embedBatch` as `packing`, sourced straight from the
- * same probe: `windowTokens` for the per-request budget, `charsPerToken` for
- * the calibrated per-text token estimate, and `windowTokens` again for
- * Ollama's `num_ctx` when `source === "ollama"`. `windowIsKnown`
- * (`source !== "default"`) gates `RemoteEmbedder`'s same-run adaptive
- * shrink: a provider that reports nothing about its own context size still
- * gets that corrective, but a probed, authoritative window does not need it
- * second-guessed.
- */
-async function resolveEmbeddingPacking(config, signal) {
-    const base = config.embedding ?? {};
-    const limits = await probeProviderLimits(base, { signal });
-    return {
-        embeddingConfig: { ...base, concurrency: base.concurrency ?? limits.slots },
-        packing: {
-            tokenBudget: limits.windowTokens,
-            charsPerToken: limits.charsPerToken,
-            windowIsKnown: limits.source !== "default",
-            ollamaNumCtx: limits.source === "ollama" ? limits.windowTokens : undefined,
-        },
-    };
-}
-/**
- * #953 field gap, ported from the deleted `materialize-embeddings.ts`
- * (`git show fc711fd6^:src/indexer/materialize-embeddings.ts`): a keyless
- * request against a remote embedding endpoint could not be reproduced in the
- * lab — every `RemoteEmbedder` path already resolves `secret://` through one
- * boundary, so a keyless request can only mean `embedding.apiKey` was absent
- * from the config THIS run loaded. The actionable outcome is a
- * self-diagnosing run, not a fix: one default-level line, emitted once
- * before the first provider request this call makes, naming the endpoint,
- * model, and credential SOURCE (never the value) so a field run can compare
- * it against what the gateway actually saw. A local (non-remote) endpoint,
- * or a call with nothing pending, has nothing to diagnose and stays silent.
- */
-function emitCredentialDiagnostic(config, onProgress) {
-    if (!onProgress || !hasRemoteEndpoint(config.embedding ?? {}))
-        return;
-    const endpoint = normalizeEmbeddingEndpoint(config.embedding?.endpoint ?? "");
-    const credential = describeEmbeddingCredential(config.embedding?.apiKey);
-    const configFileSuffix = isVerbose() ? `; config: ${getConfigPath()}` : "";
-    onProgress(`[embed] endpoint ${endpoint}, model ${config.embedding?.model ?? "unknown"}; credential: ${credential}${configFileSuffix}`);
-}
-function formatDoneLine(counts) {
-    return (`[drain] done: ${counts.pending} pending, ${counts.embedded} embedded, ${counts.failed} failed, ` +
-        `${counts.skipped} skipped (identity: ${counts.identity ?? "unknown"})`);
-}
-export async function drainEmbeddingQueue(db, config, opts = {}) {
-    throwIfAborted(opts.signal);
-    let identity = getMeta(db, "embeddingIdentity") ?? null;
-    if (config.semanticSearchMode === "off") {
-        return { pending: 0, embedded: 0, failed: 0, skipped: 0, identity };
-    }
-    const candidateHashes = opts.onlyHashes ? [...new Set(opts.onlyHashes)] : selectAllUnitHashes(db);
-    const missingHashes = identity ? listMissingHashes(db, candidateHashes, identity) : candidateHashes;
-    const pending = missingHashes.length;
-    const emitDone = (counts) => {
-        opts.onProgress?.(formatDoneLine(counts));
-        return counts;
-    };
-    // upsertUnitVectors is a no-op without sqlite-vec (units-repository.ts), so
-    // embedding the pending set here would just throw every vector away and
-    // leave it "missing" again for the next call — pure wasted provider
-    // traffic. `akmIndex`'s verification reports the missing extension as
-    // blocked; this stays silent. `pending` is computed above so the done line and `akm
-    // index status` stay truthful even though nothing was attempted.
-    if (!isVecAvailable(db)) {
-        return emitDone({ pending, embedded: 0, failed: 0, skipped: pending, identity });
-    }
-    if (pending === 0) {
-        return emitDone({ pending: 0, embedded: 0, failed: 0, skipped: 0, identity });
-    }
-    const boundedHashes = opts.limit !== undefined ? missingHashes.slice(0, opts.limit) : missingHashes;
-    const textByHash = fetchUnitTexts(db, boundedHashes);
-    // A hash in `unit_texts` should always resolve to a row (it was just read
-    // from that same table above), but a missing row is dropped rather than
-    // sent to the provider as `undefined` text.
-    const orderedHashes = boundedHashes.filter((hash) => textByHash.has(hash));
-    const texts = orderedHashes.map((hash) => textByHash.get(hash));
-    if (texts.length === 0) {
-        return emitDone({ pending, embedded: 0, failed: 0, skipped: 0, identity });
-    }
-    emitCredentialDiagnostic(config, opts.onProgress);
-    const { embeddingConfig, packing } = await resolveEmbeddingPacking(config, opts.signal);
-    let embedded = 0;
-    let failed = 0;
-    let batchNumber = 0;
-    // Two independent circuit-breaker streaks (single-document failures,
-    // network errors at any size) — see CIRCUIT_BREAKER_WINDOW above.
-    const singleDocFailureWindow = [];
-    const networkErrorFailureWindow = [];
-    // Whether this CALL has already decided the identity its first committed
-    // row observed (E1) — adoption happens at most once per call; see the
-    // module doc comment and the identity block in `onBatch` below.
-    let identityDecidedThisCall = false;
-    const onSkip = (skip) => {
-        failed++;
-        if (!skip.batchStart)
-            return undefined;
-        if (skip.reason === "context-window-exceeded") {
-            // Proves the provider IS reachable; not evidence of a dead endpoint.
-            singleDocFailureWindow.length = 0;
-            networkErrorFailureWindow.length = 0;
-            return undefined;
-        }
-        pushBreakerOutcome(singleDocFailureWindow, skip.batchSize === 1);
-        pushBreakerOutcome(networkErrorFailureWindow, skip.failureKind === "network-error");
-        if (breakerFailureCount(singleDocFailureWindow) >= CIRCUIT_BREAKER_THRESHOLD ||
-            breakerFailureCount(networkErrorFailureWindow) >= CIRCUIT_BREAKER_THRESHOLD) {
-            return false;
-        }
-        return undefined;
-    };
-    const onBatch = (indices, embeddings, model, outcome) => {
-        // "retrying"/"budget-lowered" are in-flight notices for a batch that has
-        // not settled yet (see EmbeddingBatchOutcome) — nothing to commit or
-        // count, and not a distinct "batch" for the one-line-per-batch contract.
-        if (outcome?.outcome === "retrying" || outcome?.outcome === "budget-lowered")
-            return;
-        const rows = [];
-        for (let k = 0; k < indices.length; k++) {
-            const embedding = embeddings[k];
-            if (!embedding)
-                continue;
-            const learned = deriveObservedEmbeddingIdentity(config.embedding, model, embedding.length);
-            if (!identityDecidedThisCall) {
-                // This call's FIRST committed row decides the identity it adopts
-                // (E1) — learned once, not re-derived per batch: a provider whose
-                // responses alternate between models WITHIN one call (a
-                // load-balanced gateway, a blue/green rollout behind one endpoint)
-                // must not thrash the store between them (embed, delete, re-embed,
-                // never converging). A genuine model change is still caught, just
-                // not until the NEXT call's own first batch observes it and purges
-                // whatever this call left behind.
-                identityDecidedThisCall = true;
-                if (learned && learned !== identity) {
-                    identity = learned;
-                    setMeta(db, "embeddingIdentity", identity);
-                    dropOtherIdentities(db, identity, embedding.length);
-                }
-            }
-            const currentIdentity = identity;
-            if (currentIdentity === null || learned !== currentIdentity) {
-                // Either nothing has ever been learned, or a LATER batch this same
-                // call reported an identity different from the one already adopted
-                // — left missing rather than switched to; it becomes "missing"
-                // again under whatever identity this call is using, and a later
-                // call, whose own first batch observes it, picks it up. Counted in
-                // `skipped` below (attempted minus embedded minus failed), not
-                // `embedded`.
-                continue;
-            }
-            const hash = orderedHashes[indices[k]];
-            if (hash)
-                rows.push({ hash, identity: currentIdentity, vector: embedding });
-        }
-        let storageBreakerTripped = false;
-        if (rows.length > 0) {
-            // upsertUnitVectors commits each row in its own transaction — this IS
-            // "each provider batch commits durably" (a wrapping db.transaction()
-            // here would only nest as an unobservable SAVEPOINT inside it, per the
-            // ambient-transaction hazard materialize-embeddings.ts's own drift
-            // guard documents), now made even finer-grained so one malformed
-            // vector in a batch (e.g. a width mismatch) can't roll back the rest
-            // of an otherwise-good response.
-            const result = upsertUnitVectors(db, rows);
-            embedded += result.inserted;
-            failed += result.failed;
-            if (result.failed > 0) {
-                // E5b: a write failure is just as much evidence of a broken run as
-                // a provider failure — a sustained STORAGE failure (contention,
-                // permissions, a full disk) must not keep dispatching every
-                // remaining batch to a perfectly healthy provider at full cost
-                // while every write silently fails. One event per committed batch
-                // (the "count batch starts, not documents" rule onSkip already
-                // applies to provider failures), fed into the SAME two streaks.
-                pushBreakerOutcome(singleDocFailureWindow, true);
-                pushBreakerOutcome(networkErrorFailureWindow, true);
-                if (breakerFailureCount(singleDocFailureWindow) >= CIRCUIT_BREAKER_THRESHOLD ||
-                    breakerFailureCount(networkErrorFailureWindow) >= CIRCUIT_BREAKER_THRESHOLD) {
-                    storageBreakerTripped = true;
-                }
-            }
-        }
-        if (embeddings.some((embedding) => embedding !== undefined)) {
-            pushBreakerOutcome(singleDocFailureWindow, false);
-            pushBreakerOutcome(networkErrorFailureWindow, false);
-        }
-        batchNumber++;
-        if (opts.onProgress) {
-            const docCount = outcome?.docCount ?? indices.length;
-            const label = outcome && outcome.outcome !== "stored" ? `failed: ${outcome.reason ?? "unknown"}` : `${rows.length} stored`;
-            opts.onProgress(`${DRAIN_BATCH_PROGRESS_PREFIX}${batchNumber}: ${docCount} docs → ${label}`);
-        }
-        if (storageBreakerTripped) {
-            // onBatch has no `false`-return stop-dispatch contract the way onSkip
-            // does (a storage failure can trip this even when the provider itself
-            // keeps succeeding, so onSkip is never called at all) — this reuses
-            // RemoteEmbedder's own documented mechanism instead: a throw from
-            // onBatch stops the pool from dispatching any further provider
-            // request, and is rethrown once every in-flight batch has settled.
-            throw new Error(`Circuit breaker: ${CIRCUIT_BREAKER_THRESHOLD} storage write failures while embedding; stopping further provider requests this call.`);
-        }
-    };
-    await embedBatch(texts, embeddingConfig, opts.signal, onSkip, onBatch, packing);
-    throwIfAborted(opts.signal);
-    const attempted = texts.length;
-    const skipped = Math.max(0, attempted - embedded - failed);
-    return emitDone({ pending, embedded, failed, skipped, identity });
-}

package/dist/indexer/embedding-identity.js

@@ -1,20 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { DETERMINISTIC_EMBED_MODEL_ID, isDeterministicEmbedEnabled } from "../llm/embedders/deterministic.js";
-import { DEFAULT_LOCAL_MODEL } from "../llm/embedders/local.js";
-/**
- * Returns `undefined` when nothing was actually observed this call (no
- * vector to measure yet) — there is nothing to key an identity on.
- */
-export function deriveObservedEmbeddingIdentity(embedding, observedModel, observedVectorLen) {
-    if (isDeterministicEmbedEnabled()) {
-        return `deterministic:${DETERMINISTIC_EMBED_MODEL_ID}`;
-    }
-    if (observedVectorLen === undefined)
-        return undefined;
-    if (embedding?.endpoint) {
-        return `remote:${observedModel ?? embedding.model ?? "unknown"}|${observedVectorLen}`;
-    }
-    return `local:${embedding?.localModel ?? DEFAULT_LOCAL_MODEL}|${observedVectorLen}`;
-}

package/dist/indexer/enrich.js

@@ -1,260 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-/**
- * LLM metadata-enrichment pass, restored on the reconcile path
- * (docs/plans/index-redesign-contract.md, B5e).
- *
- * Before the index redesign, `akm index` ran a config-driven metadata
- * enhancement pass over every "generated"-quality entry, keyed by a
- * `(assetRef, cacheVariant)` cache row whose `body_hash` column happened to
- * gate freshness. The reconcile rewrite (`reconcile.ts`, B1) dropped the
- * call site along with the rest of the old phase pipeline. This module
- * restores the feature on the NEW path, content-addressed throughout:
- * `reconcileRoots` collects one {@link MetadataEnrichmentCandidate} per file
- * it just upserted (added or changed) and hands the batch to
- * {@link enrichReconciledEntries} once, AFTER every per-file transaction in
- * this run has already committed — a provider call must never run inside
- * `applyChange`'s `BEGIN IMMEDIATE` transaction (docs/plans/index-redesign.md
- * rule 5: every index write stays a short, idempotent transaction; an LLM
- * call can take seconds to minutes and must not hold one open).
- *
- * **Content-addressed cache** — `llm_enrichment_cache` (still shared with
- * graph-extraction and memory-inference, which key it by absolute file path)
- * is used here with `asset_ref = body_hash = candidate.blobHash`: the cache
- * row IS the content address, so a cache hit means "this exact byte content
- * has already been enriched" regardless of which entry or how many entries
- * currently carry it, and a rename or an unrelated field edit elsewhere in
- * the same file never invalidates it. `withLlmCache` (`./db/llm-cache.ts`)
- * already implements exactly this hash-gated lookup/call/write shape, so this
- * module reuses it rather than duplicating the pattern a third time.
- *
- * **Fail-soft** — `enhanceMetadata`'s `EnhanceMetadataOutcome` distinguishes
- * `enriched` (real success — cache it) from `skipped` (feature gate closed)
- * and `failed` (provider/network error): `withLlmCache`'s "only cache a
- * defined result" contract means a `skipped`/`failed` outcome (mapped to
- * `undefined` below) writes no cache row and leaves the entry's `quality`
- * untouched, so a transient provider outage can never poison an entry into a
- * permanent enrichment skip.
- *
- * **`--full` re-applies without a new provider call** — `reconcileRoots`'s
- * `forceReparse` re-parses every file, so an unchanged file's fresh
- * `IndexDocument` is `quality: "generated"` again (enrichment only ever
- * updated the DB row, never the source file) and becomes an enrichment
- * candidate again on every `--full` run. Its `blobHash` is unchanged, so the
- * content-addressed cache lookup above hits and re-applies the SAME cached
- * fields with no new provider call — this falls out of content-addressing
- * for free and needs no `--full`-specific branch here.
- */
-import fs from "node:fs";
-import { concurrentMap } from "../core/concurrent.js";
-import { ConfigError } from "../core/errors.js";
-import { defaultConcurrencyForEndpoint } from "../core/loopback.js";
-import { withImmediateTransaction } from "../core/state-db.js";
-import { warn } from "../core/warn.js";
-import { resolveIndexPassExecution } from "../llm/index-passes.js";
-import { enhanceMetadata } from "../llm/metadata-enhance.js";
-import { insertNewUnitTexts } from "../storage/repositories/files-repository.js";
-import { upsertEntry } from "../storage/repositories/index-entries-repository.js";
-import { replaceEntryUnits } from "../storage/repositories/units-repository.js";
-import { withLlmCache } from "./db/llm-cache.js";
-import { getMarkdownFragmentContent, hasMarkdownFragmentContent, isEnrichmentComplete, setMarkdownFragmentContent, } from "./passes/metadata.js";
-import { buildSearchText } from "./search/search-fields.js";
-import { deriveUnits, toUnitSource } from "./units/unit.js";
-/**
- * Namespaces this pass's `llm_enrichment_cache` rows away from
- * graph-extraction's and memory-inference's own `cacheVariant` values, which
- * key the SAME shared table by absolute file path rather than content hash.
- */
-const METADATA_ENRICHMENT_CACHE_VARIANT = "metadata-enhance-v1";
-function emptyCounts() {
-    return { attempted: 0, cacheHits: 0, enriched: 0, failed: 0, skipped: 0 };
-}
-/** Only "generated"-quality entries missing description/tags/searchHints are worth an LLM call — see `isEnrichmentComplete`. */
-function isEligibleForEnrichment(entry) {
-    return entry.quality === "generated" && !isEnrichmentComplete(entry);
-}
-/**
- * Bounded-pool width for this pass — kept as a direct call to the shared
- * classifier (not `indexer.ts`'s `getDefaultLlmConcurrency` wrapper) to avoid
- * an indexer.ts → enrich.ts → indexer.ts import cycle, exactly like
- * `src/llm/embedders/remote.ts`'s `resolveEmbeddingConcurrency` — see that
- * function's neighboring comment. `tests/indexer/llm-concurrency-default.test.ts`
- * pins `getDefaultLlmConcurrency`'s behavior; this mirrors it exactly.
- */
-function resolveEnrichmentConcurrency(connection) {
-    if (typeof connection?.concurrency === "number")
-        return connection.concurrency;
-    return defaultConcurrencyForEndpoint(connection?.endpoint);
-}
-/**
- * Run the metadata-enrichment pass over every eligible candidate
- * `reconcileRoots` collected this run, with a bounded concurrency pool
- * (`resolveEnrichmentConcurrency`). Only called when
- * `resolveIndexPassExecution("enrichment", config)` resolves a runner — an
- * unconfigured engine, or `index.enrichment.enabled: false`, is a no-op with
- * zero cache reads and zero provider calls. The separate `metadata_enhance`
- * feature gate (`index.metadataEnhance.enabled`, default `false`) is checked
- * per-call inside `enhanceMetadata` itself, so a closed gate still shows up
- * here as a cheap `skipped` outcome rather than being special-cased twice.
- *
- * A `ConfigError` (a required symbolic credential that resolved to nothing)
- * is not fail-soft like a provider error — `enhanceMetadata` lets it escape
- * `tryLlmFeature`'s normal fallback (`llm/structured-call.ts`'s
- * `callStructured`) precisely so a genuinely broken config surfaces loudly
- * instead of reading as an ordinary per-entry failure. `concurrentMap`
- * itself swallows a thrown callback into an `undefined` slot, so this
- * catches it per-candidate and rethrows the first occurrence once every
- * in-flight candidate has settled.
- */
-export async function enrichReconciledEntries(db, config, candidates, maxChars, opts) {
-    const counts = emptyCounts();
-    const eligible = candidates.filter((candidate) => isEligibleForEnrichment(candidate.entry));
-    if (eligible.length === 0)
-        return counts;
-    const runner = resolveIndexPassExecution("enrichment", config).runner;
-    if (!runner)
-        return counts;
-    const concurrency = resolveEnrichmentConcurrency(runner.connection);
-    opts?.onProgress?.(`Metadata enrichment starting for ${eligible.length} entr${eligible.length === 1 ? "y" : "ies"} (concurrency ${concurrency}).`);
-    let configFailure;
-    await concurrentMap(eligible, async (candidate) => {
-        if (opts?.signal?.aborted)
-            return;
-        counts.attempted++;
-        try {
-            await enrichOneCandidate(db, runner, config, candidate, maxChars, counts, opts?.signal);
-        }
-        catch (err) {
-            if (err instanceof ConfigError) {
-                configFailure ??= err;
-                return;
-            }
-            throw err;
-        }
-    }, concurrency);
-    if (configFailure)
-        throw configFailure;
-    opts?.onProgress?.(`Metadata enrichment finished: ${counts.enriched} enriched (${counts.cacheHits} from cache), ` +
-        `${counts.failed} failed, ${counts.skipped} skipped.`);
-    if (counts.failed > 0 && counts.enriched === 0 && counts.skipped === 0) {
-        warn(`LLM metadata enrichment failed for all ${counts.failed} attempted entr${counts.failed === 1 ? "y" : "ies"} — ` +
-            "index built without enrichment. Check the engine selected by index.enrichment.engine (or defaults.llmEngine).");
-    }
-    return counts;
-}
-async function enrichOneCandidate(db, runner, config, candidate, maxChars, counts, signal) {
-    let sawOutcome;
-    let cacheHit = false;
-    const metadata = await withLlmCache(db, candidate.blobHash, "", false, async () => {
-        let fileContent;
-        try {
-            fileContent = fs.readFileSync(candidate.filePath, "utf8");
-        }
-        catch {
-            // Best-effort context for the prompt only — enhanceMetadata still
-            // runs (with less context) when the file cannot be re-read.
-        }
-        const outcome = await enhanceMetadata(runner, candidate.entry, fileContent, signal, config);
-        if (outcome.status !== "enriched") {
-            sawOutcome = outcome.status;
-            return undefined;
-        }
-        return outcome.metadata;
-    }, (raw) => (raw !== null && typeof raw === "object" ? raw : undefined), candidate.blobHash, METADATA_ENRICHMENT_CACHE_VARIANT, { onCacheHit: () => (cacheHit = true) });
-    if (metadata === undefined) {
-        if (sawOutcome === "failed")
-            counts.failed++;
-        else
-            counts.skipped++;
-        return;
-    }
-    let applied;
-    try {
-        applied = applyEnrichmentToEntry(db, candidate, maxChars, metadata);
-    }
-    catch (err) {
-        // A real write failure (not the stale-identity no-op below, which never
-        // throws): `concurrentMap` would otherwise swallow this into a silent
-        // undefined slot with `counts.enriched` never incremented but no record
-        // of the failure either. Surface it the same way a provider failure is
-        // already surfaced.
-        counts.failed++;
-        warn(`[index] Metadata enrichment write failed for ${candidate.filePath}: ` +
-            (err instanceof Error ? err.message : String(err)));
-        return;
-    }
-    if (!applied) {
-        // The live `entries` row no longer matches the identity this candidate
-        // was queued under (a concurrent rename or delete) — see
-        // `applyEnrichmentToEntry`. The metadata is real and already cached
-        // above, so this is reported as skipped rather than lost, and the next
-        // ordinary run re-applies it from cache with no new provider call.
-        counts.skipped++;
-        return;
-    }
-    if (cacheHit)
-        counts.cacheHits++;
-    counts.enriched++;
-}
-/**
- * Merge enrichment fields onto the candidate's entry, re-derive its units,
- * and write both through the SAME canonical entry/FTS mutation and
- * `unit_texts`/`entry_units` maintenance `applyChange` (`reconcile.ts`) uses
- * — one short `BEGIN IMMEDIATE` transaction, no `content_hash` argument so
- * `upsertEntry`'s `COALESCE` preserves the scan-derived blob hash untouched.
- *
- * Fragment units are unaffected: only `description`/`tags`/`searchHints`
- * change, which feeds solely unit ordinal 0 (`structuredFieldsText`,
- * `units/unit.ts`); `replaceEntryUnits` is still a full delete-then-insert
- * for the entry, so `getMarkdownFragmentContent`/`setMarkdownFragmentContent`
- * re-tag the merged copy — otherwise `deriveUnits` would see no markdown
- * body at all and silently drop every fragment unit `applyChange` already
- * derived for this entry.
- *
- * **Stale-identity guard** — `candidate` was captured before the LLM round
- * trip above, which can take seconds to minutes. A concurrent reconcile can
- * rename (`repointEntry` updates the SAME `entries.id` in place with a new
- * `item_ref`/`content_hash`/`file_path`) or delete this row while that call
- * was in flight. Writing the captured values regardless would either (a)
- * `upsertEntry` under the stale `item_ref`, which no longer conflicts with
- * anything and INSERTs a ghost row pointing at an identity that no longer
- * exists, or (b) `replaceEntryUnits(candidate.entryId)` overwriting a live
- * renamed row's units with the old identity's hashes — or, if the row was
- * deleted outright, throw a foreign-key error. So this re-reads the live row
- * BY ID inside the same transaction and no-ops (returns `false`, counted as
- * skipped by the caller) unless its `content_hash` and `item_ref` still
- * match what this candidate was queued under; only then is `candidate.entryId`
- * — now confirmed live, never a captured id that may no longer exist — used
- * to write.
- */
-function applyEnrichmentToEntry(db, candidate, maxChars, metadata) {
-    const merged = { ...candidate.entry, quality: "enriched" };
-    if (metadata.description)
-        merged.description = metadata.description;
-    if (metadata.tags?.length)
-        merged.tags = metadata.tags;
-    if (metadata.searchHints?.length)
-        merged.searchHints = metadata.searchHints;
-    if (hasMarkdownFragmentContent(candidate.entry)) {
-        setMarkdownFragmentContent(merged, getMarkdownFragmentContent(candidate.entry));
-    }
-    const searchText = buildSearchText(merged);
-    return withImmediateTransaction(db, () => {
-        const live = db
-            .prepare("SELECT content_hash AS contentHash, item_ref AS itemRef FROM entries WHERE id = ?")
-            .get(candidate.entryId);
-        if (!live || live.contentHash !== candidate.blobHash || live.itemRef !== candidate.provenance.itemRef) {
-            return false;
-        }
-        upsertEntry(db, candidate.filePath, merged, searchText, candidate.provenance);
-        const units = deriveUnits(toUnitSource(candidate.entryId, merged), maxChars);
-        insertNewUnitTexts(db, units.map((unit) => ({
-            hash: unit.hash,
-            kind: unit.fragmentId === null ? "card" : "fragment",
-            text: unit.text,
-        })));
-        replaceEntryUnits(db, candidate.entryId, units.map((unit) => ({ ordinal: unit.ordinal, fragmentId: unit.fragmentId, hash: unit.hash })));
-        return true;
-    }, "index");
-}