gitnexus 1.6.10-rc.21 → 1.6.10-rc.211

package/dist/core/augmentation/engine.js

@@ -41,11 +41,15 @@ async function findRepoForCwd(cwd) {
             if (normalizedCwd === normalizedRepo) {
                 matched = true;
             }
-            else if (normalizedCwd.startsWith(normalizedRepo + sep)) {
-                matched = true;
-            }
-            else if (normalizedRepo.startsWith(normalizedCwd + sep)) {
-                matched = true;
+            else {
+                const repoPrefix = normalizedRepo.endsWith(sep) ? normalizedRepo : normalizedRepo + sep;
+                const cwdPrefix = normalizedCwd.endsWith(sep) ? normalizedCwd : normalizedCwd + sep;
+                if (normalizedCwd.startsWith(repoPrefix)) {
+                    matched = true;
+                }
+                else if (normalizedRepo.startsWith(cwdPrefix)) {
+                    matched = true;
+                }
             }
             if (matched && normalizedRepo.length > bestLen) {
                 bestMatch = entry;
@@ -104,6 +108,7 @@ export async function augment(pattern, cwd) {
           MATCH (n) WHERE n.filePath = '${escaped}'
           AND n.name CONTAINS '${patternFirstWord}'
           RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath
+          ORDER BY id
           LIMIT 3
         `);
                 for (const sym of symbols) {
@@ -127,6 +132,7 @@ export async function augment(pattern, cwd) {
         MATCH (n)
         WHERE n.name CONTAINS '${patternFirstWord}'
         RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath
+        ORDER BY id
         LIMIT 5
       `).catch(() => []);
             for (const sym of fallbackRows) {
@@ -149,99 +155,112 @@ export async function augment(pattern, cwd) {
         if (uniqueSymbols.length === 0)
             return '';
         const idList = uniqueSymbols.map((s) => `'${escapeCypherString(s.nodeId)}'`).join(', ');
-        // Batch fetch callers
-        const callersMap = new Map();
-        try {
-            const rows = await executeQuery(repoId, `
-        MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(n)
-        WHERE n.id IN [${idList}]
-        RETURN n.id AS targetId, caller.name AS name
-        LIMIT 15
-      `);
-            for (const r of rows) {
-                const tid = r.targetId || r[0];
-                const name = r.name || r[1];
-                if (tid && name) {
-                    if (!callersMap.has(tid))
-                        callersMap.set(tid, []);
-                    callersMap.get(tid).push(name);
-                }
-            }
-        }
-        catch {
-            /* skip */
-        }
-        // Batch fetch callees
-        const calleesMap = new Map();
-        try {
+        // Callers/callees are windowed PER SYMBOL, not out of one shared budget.
+        // A single `n.id IN [...] ... ORDER BY targetId LIMIT 15` sorts by the very
+        // column the rows are grouped by, which turns the cap into a single-bucket
+        // prefix: the alphabetically-first target takes every row (the hottest
+        // symbol in this repo's own index has 2163 callers) and the other four
+        // render with no callers at all. Raising the cap does not bound that, and
+        // ordering caller-major only moves the bucket. A per-target window is not
+        // expressible in one statement either — LadybugDB does not preserve a
+        // per-branch ORDER BY through UNION ALL — so fan out one bounded query per
+        // symbol (#2787).
+        //
+        // `id STARTS WITH 'File:'` sorts container nodes last: node ids are
+        // `Label:path:name`, so a bare `ORDER BY id` puts `File:` ahead of
+        // `Function:`/`Method:` and the "Called by" line renders bare filenames
+        // instead of the calling symbols the hint exists to name.
+        const NEIGHBOUR_CAP = 3;
+        const neighbourNames = async (nodeId, incoming) => {
+            const edge = incoming
+                ? `(other)-[:CodeRelation {type: 'CALLS'}]->(n)`
+                : `(n)-[:CodeRelation {type: 'CALLS'}]->(other)`;
             const rows = await executeQuery(repoId, `
-        MATCH (n)-[:CodeRelation {type: 'CALLS'}]->(callee)
-        WHERE n.id IN [${idList}]
-        RETURN n.id AS sourceId, callee.name AS name
-        LIMIT 15
-      `);
+        MATCH ${edge}
+        WHERE n.id = '${escapeCypherString(nodeId)}'
+        RETURN other.name AS name
+        ORDER BY other.id STARTS WITH 'File:', other.id
+        LIMIT ${NEIGHBOUR_CAP}
+      `).catch(() => []);
+            const names = [];
             for (const r of rows) {
-                const sid = r.sourceId || r[0];
-                const name = r.name || r[1];
-                if (sid && name) {
-                    if (!calleesMap.has(sid))
-                        calleesMap.set(sid, []);
-                    calleesMap.get(sid).push(name);
-                }
+                const name = r.name || r[0];
+                if (name)
+                    names.push(name);
             }
-        }
-        catch {
-            /* skip */
-        }
+            return names;
+        };
+        // Keyed by nodeId, like the process/cohesion enrichments below — positional
+        // arrays would put two lookup disciplines in one object literal and make
+        // "stays index-aligned with uniqueSymbols" an unenforced invariant.
+        const neighbourMap = async (incoming) => new Map(await Promise.all(uniqueSymbols.map(async (s) => [s.nodeId, await neighbourNames(s.nodeId, incoming)])));
         // Batch fetch processes
-        const processesMap = new Map();
-        try {
-            const rows = await executeQuery(repoId, `
+        const fetchProcesses = async () => {
+            const byNode = new Map();
+            try {
+                const rows = await executeQuery(repoId, `
         MATCH (n)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
         WHERE n.id IN [${idList}]
         RETURN n.id AS nodeId, p.heuristicLabel AS label, r.step AS step, p.stepCount AS stepCount
       `);
-            for (const r of rows) {
-                const nid = r.nodeId || r[0];
-                const label = r.label || r[1];
-                const step = r.step || r[2];
-                const stepCount = r.stepCount || r[3];
-                if (nid && label) {
-                    if (!processesMap.has(nid))
-                        processesMap.set(nid, []);
-                    processesMap.get(nid).push(`${label} (step ${step}/${stepCount})`);
+                for (const r of rows) {
+                    const nid = r.nodeId || r[0];
+                    const label = r.label || r[1];
+                    const step = r.step || r[2];
+                    const stepCount = r.stepCount || r[3];
+                    if (nid && label) {
+                        if (!byNode.has(nid))
+                            byNode.set(nid, []);
+                        byNode.get(nid).push(`${label} (step ${step}/${stepCount})`);
+                    }
                 }
             }
-        }
-        catch {
-            /* skip */
-        }
+            catch {
+                /* skip */
+            }
+            return byNode;
+        };
         // Batch fetch cohesion
-        const cohesionMap = new Map();
-        try {
-            const rows = await executeQuery(repoId, `
+        const fetchCohesion = async () => {
+            const byNode = new Map();
+            try {
+                const rows = await executeQuery(repoId, `
         MATCH (n)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
         WHERE n.id IN [${idList}]
         RETURN n.id AS nodeId, c.cohesion AS cohesion
       `);
-            for (const r of rows) {
-                const nid = r.nodeId || r[0];
-                const coh = r.cohesion ?? r[1] ?? 0;
-                if (nid)
-                    cohesionMap.set(nid, coh);
+                for (const r of rows) {
+                    const nid = r.nodeId || r[0];
+                    const coh = r.cohesion ?? r[1] ?? 0;
+                    if (nid)
+                        byNode.set(nid, coh);
+                }
             }
-        }
-        catch {
-            /* skip */
-        }
+            catch {
+                /* skip */
+            }
+            return byNode;
+        };
+        // One wave, not three. `augment` runs from the Claude Code PreToolUse hook
+        // in a cold process against a <500ms budget, so nothing amortizes — and the
+        // process/cohesion queries depend only on `idList`, never on the neighbour
+        // results, so serializing them behind the fan-out bought nothing. Each query
+        // keeps its own try/catch, so one failing still degrades to an empty map
+        // instead of taking the others down.
+        const [callerMap, calleeMap, processesMap, cohesionMap] = await Promise.all([
+            neighbourMap(true),
+            neighbourMap(false),
+            fetchProcesses(),
+            fetchCohesion(),
+        ]);
         // Assemble enriched results
         const enriched = [];
         for (const sym of uniqueSymbols) {
             enriched.push({
                 name: sym.name,
                 filePath: sym.filePath,
-                callers: (callersMap.get(sym.nodeId) || []).slice(0, 3),
-                callees: (calleesMap.get(sym.nodeId) || []).slice(0, 3),
+                callers: callerMap.get(sym.nodeId) || [],
+                callees: calleeMap.get(sym.nodeId) || [],
                 processes: processesMap.get(sym.nodeId) || [],
                 cohesion: cohesionMap.get(sym.nodeId) || 0,
             });

package/dist/core/embedding-checkpoint.d.ts

@@ -0,0 +1,143 @@
+/**
+ * The single owner of `RepoMeta.embeddingCheckpoint` — how it is minted, and
+ * how a run decides what to do with one it finds.
+ *
+ * This module exists for the reason `embedding-count.ts` next door exists, and
+ * for a sharper one. A review of #2790 found that two hand-copied bodies of
+ * "measure the embedding count" had drifted inside a single change; the fix for
+ * that then created a SECOND pair of hand-copied publishers — of this record —
+ * and they had already drifted too: the CLI armed the attempt counter only
+ * after clearing its identity gate, the server derived it from the resumed
+ * marker alone. Worse, only one of the two READERS implemented `kind` at all,
+ * so a `'partial'` marker written by `gitnexus analyze` and resumed through
+ * `POST /api/embed` hit exactly the permanent wedge `kind` was introduced to
+ * remove. Prose promising two sites stay in step is not a mechanism. This is.
+ *
+ * Same tier as {@link ./embedding-count.ts} and {@link ./embedding-mode.ts}:
+ * type-only imports, no native dependencies, so `run-analyze.ts` can import it
+ * statically without dragging an embeddings module in (#2370) and `server/`
+ * can import it too.
+ */
+import type { RepoMeta } from '../storage/repo-manager.js';
+export type EmbeddingCheckpoint = NonNullable<RepoMeta['embeddingCheckpoint']>;
+export type EmbeddingCheckpointKind = NonNullable<EmbeddingCheckpoint['kind']>;
+export interface EmbeddingRunIdentity {
+    model: string;
+    dimensions: number;
+    provider: string;
+}
+export interface EmbeddingCheckpointProgress {
+    nodesProcessed: number;
+    totalNodes: number;
+    chunksProcessed: number;
+}
+/**
+ * How many consecutive resume attempts may fail to clear a `'partial'` pending
+ * set before it is abandoned.
+ *
+ * Not a fresh guess: it is this repo's existing per-operation retry budget —
+ * the HTTP embedder spends `HTTP_MAX_RETRIES + 1 === 3` per request and the WAL
+ * driver `CHECKPOINT_RETRY_ATTEMPTS === 3` per flush. Each attempt here is a
+ * whole analyze invocation with those budgets nested underneath, so 3 is
+ * already generous while still converging within a day of ordinary committing.
+ */
+export declare const EMBEDDING_RESUME_MAX_ATTEMPTS = 3;
+/**
+ * The one home for the back-compat default. Markers written before #2790's
+ * follow-up carry no `kind`, and they must keep the stricter behavior — an
+ * implicit default scattered across read sites is precisely how the two
+ * readers came to disagree.
+ */
+export declare const checkpointKind: (checkpoint: EmbeddingCheckpoint) => EmbeddingCheckpointKind;
+/** Pending-node count, tolerating the field's optionality. */
+export declare const pendingNodeCount: (checkpoint: EmbeddingCheckpoint) => number;
+/**
+ * The attempt-chain rule, which is the subtlest thing here and was the part
+ * that had already diverged.
+ *
+ * The counter advances only when this run resumed a `'partial'` marker AND at
+ * least one node it was handed failed AGAIN. A resume that cleared its set but
+ * lost *different* nodes is a FRESH partial, so the budget resets — otherwise a
+ * steadily-flaky endpoint would exhaust the budget on nodes that were never the
+ * problem. `undefined` rather than `0` when the streak breaks, so a clean
+ * marker serializes without the field.
+ */
+export declare const nextAttemptCount: (resumedFrom: EmbeddingCheckpoint | undefined, failedNodeIds: readonly string[]) => number | undefined;
+/**
+ * Mint the marker written BEFORE a bounded write window opens.
+ *
+ * `'interrupted'`: if the process dies inside the window these nodes may hold a
+ * subset of their chunks, which is what forces resume to delete and regenerate
+ * them even when a persisted row carries the current content hash — and what
+ * makes an identity mismatch fail closed rather than mix vector spaces. No
+ * `attempts`: the retry bound belongs to `'partial'`, whose pending set
+ * provably holds zero rows and can therefore be abandoned safely.
+ */
+export declare const mintInterruptedCheckpoint: (identity: EmbeddingRunIdentity, progress: EmbeddingCheckpointProgress, pendingNodeIds: string[], at?: string) => EmbeddingCheckpoint;
+/**
+ * Mint the marker written AFTER a run that completed while dropping nodes.
+ *
+ * `totalNodes` is reconstructed as complete + dropped, because `nodesProcessed`
+ * counts only the nodes that finished with a full row set. It feeds the resume
+ * log line and nothing else.
+ */
+export declare const mintPartialCheckpoint: (identity: EmbeddingRunIdentity, result: {
+    nodesProcessed: number;
+    chunksProcessed: number;
+    failedNodeIds: string[];
+}, resumedFrom: EmbeddingCheckpoint | undefined, at?: string) => EmbeddingCheckpoint;
+/**
+ * Mint the marker written when a run finished but its embedding count could not
+ * be verified.
+ *
+ * A third state, and it needs its own `kind` rather than borrowing `'partial'`:
+ * its pending set is EMPTY. Nothing was dropped and nothing needs re-embedding
+ * — the marker exists only to defeat the same-commit fast return so the next
+ * run re-derives a count, because clearing it while `stats.embeddings` still
+ * reads a stale zero is what arms a later `--force` to wipe live embeddings.
+ * Stamping it `'partial'` made `gitnexus status` tell the operator that N nodes
+ * had lost their embeddings, where N is zero.
+ */
+export declare const mintUnverifiedCountCheckpoint: (identity: EmbeddingRunIdentity, progress: EmbeddingCheckpointProgress, at?: string) => EmbeddingCheckpoint;
+export type EmbeddingResumeDecision = 
+/** An explicit flag cleared it; nothing to resume. */
+{
+    readonly action: 'discard';
+    readonly log: string;
+}
+/**
+ * Keep running, but abandon the pending set — either the retry budget is
+ * spent, or the marker was written by a different embedding identity whose
+ * nodes provably hold zero rows so nothing is at risk.
+ */
+ | {
+    readonly action: 'abandon';
+    readonly log: string;
+}
+/** Resume: regenerate `pendingNodeIds` under the matching identity. */
+ | {
+    readonly action: 'resume';
+    readonly log: string;
+    readonly pendingNodeIds: ReadonlySet<string>;
+    readonly resumedFrom: EmbeddingCheckpoint;
+}
+/** Fail closed: a half-written window under a foreign identity. */
+ | {
+    readonly action: 'abort';
+    readonly error: string;
+};
+/**
+ * The one implementation of "what should this run do with the checkpoint it
+ * found", shared by the CLI resume gate and `POST /api/embed`.
+ *
+ * Callers resolve the embedding identity lazily and pass it only when they need
+ * a verdict beyond the flag checks — resolving it is not free, and the flag
+ * paths short-circuit before it is needed. Pass `identity: undefined` to get
+ * just those; a decision that requires an identity returns `'resume'` only when
+ * one was supplied and matched.
+ */
+export declare const decideEmbeddingResume: (checkpoint: EmbeddingCheckpoint, identity: EmbeddingRunIdentity | undefined, options?: {
+    force?: boolean;
+    dropEmbeddings?: boolean;
+    maxAttempts?: number;
+}) => EmbeddingResumeDecision;

package/dist/core/embedding-checkpoint.js

@@ -0,0 +1,221 @@
+/**
+ * The single owner of `RepoMeta.embeddingCheckpoint` — how it is minted, and
+ * how a run decides what to do with one it finds.
+ *
+ * This module exists for the reason `embedding-count.ts` next door exists, and
+ * for a sharper one. A review of #2790 found that two hand-copied bodies of
+ * "measure the embedding count" had drifted inside a single change; the fix for
+ * that then created a SECOND pair of hand-copied publishers — of this record —
+ * and they had already drifted too: the CLI armed the attempt counter only
+ * after clearing its identity gate, the server derived it from the resumed
+ * marker alone. Worse, only one of the two READERS implemented `kind` at all,
+ * so a `'partial'` marker written by `gitnexus analyze` and resumed through
+ * `POST /api/embed` hit exactly the permanent wedge `kind` was introduced to
+ * remove. Prose promising two sites stay in step is not a mechanism. This is.
+ *
+ * Same tier as {@link ./embedding-count.ts} and {@link ./embedding-mode.ts}:
+ * type-only imports, no native dependencies, so `run-analyze.ts` can import it
+ * statically without dragging an embeddings module in (#2370) and `server/`
+ * can import it too.
+ */
+/**
+ * How many consecutive resume attempts may fail to clear a `'partial'` pending
+ * set before it is abandoned.
+ *
+ * Not a fresh guess: it is this repo's existing per-operation retry budget —
+ * the HTTP embedder spends `HTTP_MAX_RETRIES + 1 === 3` per request and the WAL
+ * driver `CHECKPOINT_RETRY_ATTEMPTS === 3` per flush. Each attempt here is a
+ * whole analyze invocation with those budgets nested underneath, so 3 is
+ * already generous while still converging within a day of ordinary committing.
+ */
+export const EMBEDDING_RESUME_MAX_ATTEMPTS = 3;
+/**
+ * The one home for the back-compat default. Markers written before #2790's
+ * follow-up carry no `kind`, and they must keep the stricter behavior — an
+ * implicit default scattered across read sites is precisely how the two
+ * readers came to disagree.
+ */
+export const checkpointKind = (checkpoint) => checkpoint.kind ?? 'interrupted';
+/** Pending-node count, tolerating the field's optionality. */
+export const pendingNodeCount = (checkpoint) => checkpoint.pendingNodeIds?.length ?? 0;
+/**
+ * The attempt-chain rule, which is the subtlest thing here and was the part
+ * that had already diverged.
+ *
+ * The counter advances only when this run resumed a `'partial'` marker AND at
+ * least one node it was handed failed AGAIN. A resume that cleared its set but
+ * lost *different* nodes is a FRESH partial, so the budget resets — otherwise a
+ * steadily-flaky endpoint would exhaust the budget on nodes that were never the
+ * problem. `undefined` rather than `0` when the streak breaks, so a clean
+ * marker serializes without the field.
+ */
+export const nextAttemptCount = (resumedFrom, failedNodeIds) => {
+    if (resumedFrom === undefined || checkpointKind(resumedFrom) !== 'partial')
+        return undefined;
+    const resumedPending = new Set(resumedFrom.pendingNodeIds ?? []);
+    const failedAgain = failedNodeIds.some((id) => resumedPending.has(id));
+    return failedAgain ? (resumedFrom.attempts ?? 0) + 1 : undefined;
+};
+/**
+ * Mint the marker written BEFORE a bounded write window opens.
+ *
+ * `'interrupted'`: if the process dies inside the window these nodes may hold a
+ * subset of their chunks, which is what forces resume to delete and regenerate
+ * them even when a persisted row carries the current content hash — and what
+ * makes an identity mismatch fail closed rather than mix vector spaces. No
+ * `attempts`: the retry bound belongs to `'partial'`, whose pending set
+ * provably holds zero rows and can therefore be abandoned safely.
+ */
+export const mintInterruptedCheckpoint = (identity, progress, pendingNodeIds, at = new Date().toISOString()) => ({
+    at,
+    ...progress,
+    model: identity.model,
+    dimensions: identity.dimensions,
+    provider: identity.provider,
+    kind: 'interrupted',
+    pendingNodeIds,
+});
+/**
+ * Mint the marker written AFTER a run that completed while dropping nodes.
+ *
+ * `totalNodes` is reconstructed as complete + dropped, because `nodesProcessed`
+ * counts only the nodes that finished with a full row set. It feeds the resume
+ * log line and nothing else.
+ */
+export const mintPartialCheckpoint = (identity, result, resumedFrom, at = new Date().toISOString()) => ({
+    at,
+    nodesProcessed: result.nodesProcessed,
+    totalNodes: result.nodesProcessed + result.failedNodeIds.length,
+    chunksProcessed: result.chunksProcessed,
+    model: identity.model,
+    dimensions: identity.dimensions,
+    provider: identity.provider,
+    kind: 'partial',
+    attempts: nextAttemptCount(resumedFrom, result.failedNodeIds),
+    pendingNodeIds: result.failedNodeIds,
+});
+/**
+ * Mint the marker written when a run finished but its embedding count could not
+ * be verified.
+ *
+ * A third state, and it needs its own `kind` rather than borrowing `'partial'`:
+ * its pending set is EMPTY. Nothing was dropped and nothing needs re-embedding
+ * — the marker exists only to defeat the same-commit fast return so the next
+ * run re-derives a count, because clearing it while `stats.embeddings` still
+ * reads a stale zero is what arms a later `--force` to wipe live embeddings.
+ * Stamping it `'partial'` made `gitnexus status` tell the operator that N nodes
+ * had lost their embeddings, where N is zero.
+ */
+export const mintUnverifiedCountCheckpoint = (identity, progress, at = new Date().toISOString()) => ({
+    at,
+    ...progress,
+    model: identity.model,
+    dimensions: identity.dimensions,
+    provider: identity.provider,
+    kind: 'unverified-count',
+    pendingNodeIds: [],
+});
+/**
+ * The one implementation of "what should this run do with the checkpoint it
+ * found", shared by the CLI resume gate and `POST /api/embed`.
+ *
+ * Callers resolve the embedding identity lazily and pass it only when they need
+ * a verdict beyond the flag checks — resolving it is not free, and the flag
+ * paths short-circuit before it is needed. Pass `identity: undefined` to get
+ * just those; a decision that requires an identity returns `'resume'` only when
+ * one was supplied and matched.
+ */
+export const decideEmbeddingResume = (checkpoint, identity, options = {}) => {
+    const kind = checkpointKind(checkpoint);
+    const pending = pendingNodeCount(checkpoint);
+    const maxAttempts = options.maxAttempts ?? EMBEDDING_RESUME_MAX_ATTEMPTS;
+    if (options.dropEmbeddings) {
+        return { action: 'discard', log: 'Discarding the embedding checkpoint (--drop-embeddings).' };
+    }
+    if (options.force) {
+        return {
+            action: 'discard',
+            log: 'Discarding the embedding checkpoint (--force)' +
+                `${pending > 0 ? ` and its ${pending} pending node(s)` : ''}; this run rebuilds from ` +
+                'scratch. Pass --embeddings to regenerate them explicitly.',
+        };
+    }
+    // Only the 'unverified-count' marker may skip the identity gate. Its pending
+    // set is empty BY DEFINITION and it exists purely to force a fresh count, so
+    // there is nothing a foreign embedding identity could corrupt.
+    //
+    // An empty pending set alone must NOT take this path. `onCheckpoint` mints an
+    // 'interrupted' marker with `pendingNodeIds: []` after every post-window
+    // save, and legacy markers may omit the field entirely — so keying on
+    // emptiness would silently clear an interrupted marker under a foreign
+    // provider instead of failing closed, which is exactly the vector-space
+    // mixing the 'interrupted' kind exists to prevent.
+    if (kind === 'unverified-count') {
+        return {
+            action: 'abandon',
+            log: 'Re-deriving the embedding count left unverified by the previous run.',
+        };
+    }
+    if (kind === 'partial' && (checkpoint.attempts ?? 0) >= maxAttempts) {
+        return {
+            action: 'abandon',
+            log: `Warning: ${pending} node(s) failed to embed on ${checkpoint.attempts} consecutive ` +
+                'resume attempts and are being abandoned (#2790). The index is registered without ' +
+                'them; `gitnexus status` stops reporting it as incomplete. Re-run ' +
+                '`gitnexus analyze --embeddings --force` once the embedding endpoint accepts them.',
+        };
+    }
+    if (identity === undefined) {
+        return {
+            action: 'abort',
+            error: 'Cannot resume embedding checkpoint: no embedding identity was resolved.',
+        };
+    }
+    const providerDiffers = checkpoint.provider !== identity.provider;
+    const identityDiffers = providerDiffers ||
+        checkpoint.model !== identity.model ||
+        checkpoint.dimensions !== identity.dimensions;
+    if (identityDiffers && kind !== 'interrupted') {
+        // Those nodes hold zero rows, so there is no vector space to mix. Throwing
+        // here is what turned an exit-0 partial run into a permanent wedge: a hook
+        // or CI job without the endpoint's env vars resolves `provider: 'local'`,
+        // mismatches, and dies before any phase runs.
+        return {
+            action: 'abandon',
+            log: `Warning: dropping ${pending} pending node(s) from a ${kind} embedding checkpoint: it ` +
+                `was written by a different embedding configuration (${checkpoint.model} at ` +
+                `${checkpoint.dimensions} dimensions) than this run resolves (${identity.model} at ` +
+                `${identity.dimensions}). Those nodes hold no embedding rows, so nothing is lost that ` +
+                'a later `--embeddings` run cannot regenerate.',
+        };
+    }
+    if (providerDiffers) {
+        return {
+            action: 'abort',
+            error: 'Cannot resume embedding checkpoint: the embedding provider configuration differs. ' +
+                'Restore the matching endpoint configuration or pass --drop-embeddings to rebuild without it.',
+        };
+    }
+    if (identityDiffers) {
+        return {
+            action: 'abort',
+            error: `Cannot resume embedding checkpoint: it uses ${checkpoint.model} at ` +
+                `${checkpoint.dimensions} dimensions, but this run resolves ${identity.model} at ` +
+                `${identity.dimensions}. Restore the matching embedding configuration or pass ` +
+                '--drop-embeddings to rebuild without it.',
+        };
+    }
+    // Reached with an EMPTY pending set too — an 'interrupted' marker written by
+    // a post-window save names none. That still resumes rather than clearing:
+    // the marker's presence is what forces embedding generation on a run that
+    // would otherwise derive `shouldGenerateEmbeddings: false`, and it has now
+    // cleared the identity gate, so resuming is safe.
+    return {
+        action: 'resume',
+        log: `Previous analyze ended at an embedding checkpoint (${checkpoint.nodesProcessed}/` +
+            `${checkpoint.totalNodes} nodes); resuming from persisted hashes` +
+            `${pending > 0 ? ` and regenerating ${pending} pending node(s)` : ''}.`,
+        pendingNodeIds: new Set(checkpoint.pendingNodeIds ?? []),
+        resumedFrom: checkpoint,
+    };
+};

package/dist/core/embedding-count.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The single implementation of "how many embedding rows are actually persisted".
+ *
+ * Lives in its own module — beside {@link ./embedding-mode.ts} and with the same
+ * no-native-imports property — because the CLI (`run-analyze.ts`) and the server
+ * (`server/api.ts`) both publish `RepoMeta.stats.embeddings`, and a review of
+ * #2790 found the two hand-copied bodies had already drifted inside a single
+ * change: one used `?? Number.NaN`, the other `?? 0`, under a comment asserting
+ * they measured the field "the same way". Two publishers of one field must not
+ * be able to disagree, so there is now one function and three call sites.
+ *
+ * Keeping it out of `core/embeddings/` is deliberate: `run-analyze.ts` may only
+ * reach embedding modules through `await import(...)` (#2370 — no embeddings
+ * module loads unless a run actually needs one), and this counter runs on the
+ * ordinary finalization path of every analyze.
+ *
+ * TRI-STATE, and the asymmetry is the whole point. `unknown` means COULD NOT
+ * ASK — the query throws for reasons that have nothing to do with how many rows
+ * were written (table missing, connection closed, DB busy or read-only, the
+ * VECTOR-extension DML lock #2623) — and a fabricated count is never returned in
+ * its place. A wrong-LOW value is the dangerous direction: `stats.embeddings` is
+ * the sole input to the next run's `existingEmbeddingCount` → `deriveEmbeddingMode`
+ * → `shouldLoadCache`, so a false `0` is exactly what makes a later `--force`
+ * wipe live embeddings without loading the cache.
+ */
+/** Callback shape both callers already satisfy with their `executeQuery`. */
+export type EmbeddingCountQuery = (cypher: string) => Promise<Array<Record<string, unknown>> | undefined>;
+export type PersistedEmbeddingCount = {
+    readonly kind: 'measured';
+    readonly count: number;
+}
+/** `reason` is operator-facing: each caller phrases its own warning around it. */
+ | {
+    readonly kind: 'unknown';
+    readonly reason: string;
+};
+export declare const EMBEDDING_COUNT_CYPHER = "MATCH (e:CodeEmbedding) RETURN count(e) AS cnt";
+/**
+ * Count the persisted embedding rows, or report that the answer never arrived.
+ *
+ * A MISSING row or cell counts as unknown, NOT as zero: an empty table still
+ * answers with one row holding `0`, so no row / no cell means the query did not
+ * really answer. That distinction is what `?? Number.NaN` buys — with `?? 0`,
+ * `Number.isFinite(0)` is true and the unknown branch becomes unreachable for
+ * exactly the case it exists to catch.
+ */
+export declare const measurePersistedEmbeddingCount: (runQuery: EmbeddingCountQuery) => Promise<PersistedEmbeddingCount>;
+/** `undefined` ≡ unknown, for the call sites that only need the optional number. */
+export declare const persistedEmbeddingCountOrUndefined: (result: PersistedEmbeddingCount) => number | undefined;
+/**
+ * Fold a measurement into the `RepoMeta.stats.embeddings` a run publishes.
+ *
+ * The measurement was already shared; this fold was not, and it is the half
+ * that decides what actually lands on disk — the CLI's finalization and the
+ * server's `withMeasuredEmbeddingCount` each carried their own copy of the same
+ * two lines. NEVER a fabricated `0`: `unknown` carries `priorCount` forward
+ * (see this file's header for the chain a false zero arms), and `undefined` in
+ * means `undefined` out, so a repo that never had a count keeps the field
+ * absent rather than gaining an invented one.
+ */
+export declare const resolvePersistedEmbeddingCount: (measured: PersistedEmbeddingCount, priorCount: number | undefined) => number | undefined;