@remnic/coding-graph 9.3.759

package/src/semantic/similarity.ts

@@ -0,0 +1,268 @@
+/**
+ * SIMILAR_TO near-clone pipeline (issue #1556 PR2 component).
+ *
+ * Cheap-first, deterministic:
+ *   1. MinHash/LSH candidate generation over normalized symbol bodies.
+ *   2. Cosine confirmation by embedding ≥ threshold when vectors exist.
+ *
+ * Edges carry `provenance: "semantic"` + the similarity score as
+ * confidence. No provider → MinHash-only edges carry a distinct lower
+ * confidence band (documented), and the pipeline still runs (MinHash is
+ * local and deterministic).
+ *
+ * Rule 35 spirit: the threshold boundary (≥ vs >) is decided ONCE here
+ * (≥ threshold confirms) and documented. The boundary test pins it.
+ *
+ * Rule 38: the candidate set is a pure function of (seeds, inputs). Two
+ * runs over the same fixture produce an identical edge set.
+ */
+import { readFileSync as fsReadFileSync } from "node:fs";
+import path from "node:path";
+const fs = { readFileSync: fsReadFileSync };
+import type { GraphStore } from "../graph-store.js";
+import type { EdgeIR } from "../graph-store.js";
+import { extractBodyText } from "./canonical-text.js";
+import {
+  MINHASH_ONLY_CONFIDENCE,
+  SEMANTIC_PROVENANCE,
+  SIMILAR_TO_EDGE_TYPE,
+} from "./config.js";
+import type { SemanticConfig } from "./config.js";
+import { cosineSimilarity, createMinHasher, tokenizeForShingling, shingleSet } from "./minhash.js";
+import type { SimilarEdge, SimilarToResult } from "./types.js";
+import type { SemanticFailure } from "./types.js";
+import { modelIdFor } from "./vectors.js";
+import type { HostEmbeddingProvider } from "@remnic/core/host-embedding-provider";
+
+/**
+ * Input to {@link computeSimilarTo}.
+ */
+export interface SimilarToInput {
+  readonly store: GraphStore;
+  readonly provider: HostEmbeddingProvider | undefined;
+  readonly config: SemanticConfig;
+  /**
+   * Repo root for reading source text from disk when bodies are not
+   * supplied. Required when bodies is absent.
+   */
+  readonly repoRoot?: string;
+  /**
+   * Symbol bodies keyed by nodeId. The caller (the indexer or a
+   * standalone pass) reads source text and builds canonical bodies. When
+   * absent, the pipeline reads nodes from the store + disk itself.
+   */
+  readonly bodies?: ReadonlyMap<string, { readonly qualifiedName: string; readonly body: string }>;
+  /**
+   * Vectors keyed by nodeId (the persisted embedding). When absent, the
+   * pipeline reads them from the store via readAllSymbolVectors.
+   */
+  readonly vectors?: ReadonlyMap<string, Float32Array>;
+}
+
+/**
+ * The comparison operator for cosine confirmation. Decided ONCE (rule 35
+ * spirit): `>= threshold`. A pair at EXACTLY the threshold confirms. The
+ * boundary test asserts this.
+ */
+export const CONFIRM_OPERATOR = ">=" as const;
+
+/**
+ * Jaccard gate for MinHash-only SIMILAR_TO edges (no embedding provider).
+ * Well below the cosine similarToThreshold (0.92) because token-Jaccard
+ * for near-clone code is typically 0.3-0.8. 0.5 catches genuine
+ * copy-paste with minor renames while rejecting structurally-similar
+ * but logically-unrelated pairs.
+ */
+export const MINHASH_JACCARD_GATE = 0.5;
+
+/**
+ * Compute SIMILAR_TO edges.
+ *
+ * Returns the edges (for the caller to persist via store.upsertEdges) plus
+ * counts. The caller persists; this function is pure over its inputs
+ * (rule 38 — deterministic given seeds + bodies + vectors).
+ *
+ * When `config.enabled` is false → tagged semantic_disabled (no work, no
+ * candidate generation — gate-off parity).
+ */
+export function computeSimilarTo(input: SimilarToInput): SimilarToResult | SemanticFailure {
+  const { store, provider, config } = input;
+  if (!config.enabled) {
+    return { ok: false, code: "semantic_disabled" };
+  }
+
+  // Without pre-built bodies AND without a repoRoot, the only available
+  // text is the qualified name, which MinHashes name similarity rather
+  // than body similarity — real copy-paste clones with different names
+  // are silently missed. Refuse to guess: require one of the two so the
+  // pipeline always MinHashes actual symbol bodies (chatgpt-codex-
+  // connector P2: 'Require source bodies before MinHashing').
+  if (!input.bodies && !input.repoRoot) {
+    return {
+      ok: false,
+      code: "repo_root_unset",
+      message: "computeSimilarTo needs either 'bodies' or 'repoRoot' to read source text",
+    };
+  }
+  // Closed store is a distinct degradation (rule 34) — readNodesForSemantic
+  // would return [] and we would report { ok: true, edges: [] } instead of
+  // the documented store_closed code used by the other entry points (cursor
+  // Bugbot: 'SimilarTo ignores closed store').
+  if (store.isClosed) {
+    return { ok: false, code: "store_closed" };
+  }
+  const bodies = input.bodies ?? readBodiesFromStore(store, input.repoRoot);
+  const modelId = provider ? modelIdFor(provider) : undefined;
+  const vectors = input.vectors ?? (modelId ? readVectorsMap(store, modelId) : new Map<string, Float32Array>());
+
+  // Pass 1: MinHash/LSH candidates.
+  const hasher = createMinHasher();
+  for (const [nodeId, entry] of bodies) {
+    hasher.add({ nodeId, qualifiedName: entry.qualifiedName, body: entry.body });
+  }
+  const candidates = hasher.findCandidates();
+
+  // Pass 2: cosine confirmation.
+  const edges: SimilarEdge[] = [];
+  let confirmed = 0;
+  let minhashOnly = 0;
+  for (const c of candidates) {
+    const va = vectors.get(c.aNodeId);
+    const vb = vectors.get(c.bNodeId);
+    if (va && vb && va.length === vb.length) {
+      // Require matching dimensionality — cosineSimilarity compares over the
+      // shorter length, so mismatched-dims rows would get a misleading
+      // partial-overlap score (cursor Bugbot: 'SimilarTo skips embedding
+      // length check'). Pairs that fail this fall through to the no-provider
+      // MinHash-only branch or are skipped.
+      const cos = cosineSimilarity(va, vb);
+      // rule 35: >= threshold confirms (decided once, here).
+      if (cos >= config.similarToThreshold) {
+        edges.push({
+          srcNodeId: c.aNodeId,
+          dstNodeId: c.bNodeId,
+          srcQualifiedName: c.aQualifiedName,
+          dstQualifiedName: c.bQualifiedName,
+          confidence: cos,
+          confirmed: true,
+        });
+        confirmed += 1;
+      }
+    } else if (!provider) {
+      // MinHash-only is the documented fallback for the NO-PROVIDER
+      // (local, deterministic) mode. When a provider IS configured we do
+      // NOT emit MinHash-only edges for pairs missing a vector — that
+      // would bypass the cosine confirmation path during partial / not-
+      // yet-indexed state. Such pairs are simply skipped; they will be
+      // cosine-confirmed once indexing completes (cursor Bugbot: 'MinHash
+      // edges with provider set'). Use a Jaccard gate well below the
+      // cosine threshold — MinHash Jaccard for near-clones is typically
+      // 0.3-0.8; the MINHASH_JACCARD_GATE is the documented floor.
+      if (c.jaccard >= MINHASH_JACCARD_GATE) {
+        edges.push({
+          srcNodeId: c.aNodeId,
+          dstNodeId: c.bNodeId,
+          srcQualifiedName: c.aQualifiedName,
+          dstQualifiedName: c.bQualifiedName,
+          confidence: MINHASH_ONLY_CONFIDENCE,
+          confirmed: false,
+        });
+        minhashOnly += 1;
+      }
+    }
+    // else: provider configured but a vector is missing → skip (await
+    // indexing + cosine confirmation; do not bypass with MinHash-only).
+  }
+
+  // Stable sort: by confidence desc, then src qname, then dst qname.
+  edges.sort((a, b) => {
+    if (b.confidence !== a.confidence) return b.confidence - a.confidence;
+    if (a.srcQualifiedName !== b.srcQualifiedName) return a.srcQualifiedName < b.srcQualifiedName ? -1 : 1;
+    return a.dstQualifiedName < b.dstQualifiedName ? -1 : a.dstQualifiedName > b.dstQualifiedName ? 1 : 0;
+  });
+
+  return { ok: true, edges, candidates: candidates.length, confirmed, minhashOnly };
+}
+
+/**
+ * Convert SimilarEdge[] to the store's EdgeIR[] for persistence via
+ * upsertEdges. Provenance is always "semantic"; type is SIMILAR_TO.
+ *
+ * Carries the content-derived node ids onto the EdgeIR (issue #1677) so
+ * the store resolves each endpoint by `nodes.id` (unique) instead of by
+ * qualified name — two symbols that share a qualified name across files
+ * get distinct, non-colliding SIMILAR_TO edges instead of being dropped
+ * as ambiguous.
+ */
+export function similarEdgesToEdgeIR(edges: readonly SimilarEdge[]): EdgeIR[] {
+  return edges.map((e) => ({
+    srcQualifiedName: e.srcQualifiedName,
+    dstQualifiedName: e.dstQualifiedName,
+    type: SIMILAR_TO_EDGE_TYPE,
+    confidence: e.confidence,
+    provenance: SEMANTIC_PROVENANCE,
+    srcNodeId: e.srcNodeId,
+    dstNodeId: e.dstNodeId,
+  }));
+}
+
+/**
+ * Read canonical bodies for every persisted node from the store + disk.
+ * Used when the caller does not supply pre-built bodies. Returns a map
+ * keyed by nodeId with the canonical body text (the MinHash input).
+ *
+ * Note: this reads from disk synchronously per node, so callers that
+ * already have bodies in memory should pass them via `input.bodies`.
+ */
+function readBodiesFromStore(store: GraphStore, repoRoot?: string): Map<string, { readonly qualifiedName: string; readonly body: string }> {
+  const out = new Map<string, { readonly qualifiedName: string; readonly body: string }>();
+  for (const node of store.readNodesForSemantic()) {
+    let rawText = "";
+    if (repoRoot) {
+      try {
+        const abs = path.resolve(repoRoot, node.filePath);
+        const bytes = fs.readFileSync(abs);
+        const start = Math.max(0, node.startByte);
+        const end = Math.min(bytes.length, node.endByte);
+        if (start <= end) rawText = bytes.subarray(start, end).toString("utf8");
+      } catch {
+        // File not readable — body stays empty, symbol is skipped by MinHasher.
+      }
+    }
+    // MinHash the extracted BODY only, not the full canonical text. The
+    // canonical form includes KIND/QNAME/SIG metadata; tokenizing it would
+    // let empty-body stubs/declarations emit name-driven candidates among
+    // unrelated symbols. extractBodyText returns "" for a bodyless symbol,
+    // and the hasher skips empty bodies entirely (chatgpt-codex-connector:
+    // 'MinHash only the extracted body text').
+    const body = extractBodyText(rawText, 0);
+    out.set(node.nodeId, { qualifiedName: node.qualifiedName, body });
+  }
+  return out;
+}
+
+/**
+ * Read the vectors table into a nodeId → Float32Array map for cosine
+ * confirmation. Uses the model id derived from the provider.
+ */
+function readVectorsMap(store: GraphStore, modelId: string): Map<string, Float32Array> {
+  const out = new Map<string, Float32Array>();
+  for (const row of store.readAllSymbolVectors(modelId)) {
+    out.set(row.nodeId, row.vector);
+  }
+  return out;
+}
+
+/**
+ * Estimate Jaccard similarity between two bodies directly (no LSH). Used
+ * by the hard-negative test to assert two bodies are NOT similar.
+ */
+export function estimateJaccard(bodyA: string, bodyB: string): number {
+  const sa = shingleSet(tokenizeForShingling(bodyA));
+  const sb = shingleSet(tokenizeForShingling(bodyB));
+  if (sa.size === 0 && sb.size === 0) return 1;
+  let inter = 0;
+  for (const s of sa) if (sb.has(s)) inter += 1;
+  const union = sa.size + sb.size - inter;
+  return union === 0 ? 0 : inter / union;
+}

package/src/semantic/types.ts

@@ -0,0 +1,145 @@
+/**
+ * Shared types for the semantic layer (issue #1556).
+ *
+ * Tagged failures follow rule 34 — every entry point returns a
+ * discriminated union so a caller that switches on `result.code` never
+ * observes a thrown error from the semantic layer.
+ */
+
+/**
+ * A persisted symbol vector. `vector` is the float32 embedding; `dims`
+ * is its dimensionality; `modelId` identifies the provider+model that
+ * produced it (so a provider swap invalidates the cache); `contentHash`
+ * is the canonical-text hash (so a canonical-text change invalidates the
+ * cache — rule 37).
+ */
+export interface SymbolVector {
+  readonly nodeId: string;
+  readonly qualifiedName: string;
+  readonly vector: Float32Array;
+  readonly dims: number;
+  readonly modelId: string;
+  readonly contentHash: string;
+}
+
+/**
+ * A row read back from the vectors table for brute-force cosine.
+ */
+export interface SymbolVectorRow {
+  readonly nodeId: string;
+  readonly qualifiedName: string;
+  readonly vector: Float32Array;
+  readonly dims: number;
+  readonly modelId: string;
+  readonly contentHash: string;
+  readonly filePath: string;
+}
+
+/**
+ * Tagged-failure codes shared across the semantic layer.
+ *
+ * - `semantic_disabled`: the master gate is off (rule 30/48). No provider
+ *   call, no vectors-table write, no edge emitted.
+ * - `provider_unavailable`: no host embedding provider registered for the
+ *   given scope.
+ * - `provider_timeout`: the provider exceeded the lookup budget.
+ * - `malformed_vector`: `normalizeHostEmbeddingVector` returned null.
+ * - `repo_root_unset`: the store was opened without a repoRoot, so source
+ *   text cannot be read.
+ * - `store_closed`: the store is closed.
+ * - `db_error`: an underlying SQLite error.
+ * - `no_vectors`: semantic_query ran but the vectors table is empty.
+ * - `invalid_query`: malformed query input.
+ */
+export type SemanticFailureCode =
+  | "semantic_disabled"
+  | "provider_unavailable"
+  | "provider_timeout"
+  | "malformed_vector"
+  | "repo_root_unset"
+  | "store_closed"
+  | "db_error"
+  | "no_vectors"
+  | "invalid_query";
+
+export interface SemanticFailure {
+  readonly ok: false;
+  readonly code: SemanticFailureCode;
+  readonly message?: string;
+}
+
+/**
+ * Result of indexing vectors for a batch of symbols.
+ */
+export interface IndexVectorsResult {
+  readonly ok: true;
+  readonly embedded: number;
+  readonly cached: number;
+  readonly skipped: number;
+}
+
+/**
+ * A SIMILAR_TO candidate pair from the MinHash/LSH pass.
+ */
+export interface SimilarCandidate {
+  readonly aNodeId: string;
+  readonly bNodeId: string;
+  readonly aQualifiedName: string;
+  readonly bQualifiedName: string;
+  readonly jaccard: number;
+}
+
+/**
+ * A confirmed SIMILAR_TO edge (after cosine confirmation when available).
+ *
+ * Carries the content-derived node ids (`nodes.id`) of both endpoints so
+ * the persisted edge resolves unambiguously even when the two symbols share
+ * a qualified name across files (issue #1677). The qualified-name fields
+ * remain for diagnostics / stable-sort tie-breaking.
+ */
+export interface SimilarEdge {
+  readonly srcNodeId: string;
+  readonly dstNodeId: string;
+  readonly srcQualifiedName: string;
+  readonly dstQualifiedName: string;
+  readonly confidence: number;
+  readonly confirmed: boolean;
+}
+
+/**
+ * Result of the SIMILAR_TO pipeline.
+ */
+export interface SimilarToResult {
+  readonly ok: true;
+  readonly edges: readonly SimilarEdge[];
+  readonly candidates: number;
+  readonly confirmed: number;
+  readonly minhashOnly: number;
+}
+
+/**
+ * A hydrated semantic_query hit — graph context attached so the agent
+ * gets structure, not just a snippet.
+ */
+export interface SemanticQueryHit {
+  readonly qualifiedName: string;
+  readonly filePath: string;
+  readonly kind: string;
+  readonly score: number;
+  readonly snippet: string;
+  readonly callers: readonly string[];
+  readonly callees: readonly string[];
+}
+
+/**
+ * Result of semantic_query. When degraded, `ok: true` still carries the
+ * (possibly empty) hits plus a `degraded` tag so the caller never
+ * mistakes "no matches" for "backend broken" (rule 34).
+ */
+export interface SemanticQuerySuccess {
+  readonly ok: true;
+  readonly hits: readonly SemanticQueryHit[];
+  readonly degraded?: "provider_unavailable" | "provider_timeout" | "malformed_vector";
+}
+
+export type SemanticQueryOutcome = SemanticQuerySuccess | SemanticFailure;

package/src/semantic/vectors.ts

@@ -0,0 +1,235 @@
+/**
+ * Symbol-vector indexing (issue #1556 PR1 component).
+ *
+ * Reads source text from disk, builds canonical text, checks the cache
+ * (skip re-embed when content_hash matches), embeds via the host provider,
+ * and persists vectors to the `symbol_vectors` table.
+ *
+ * Rule 30/48: when `config.enabled` is false, this module returns a tagged
+ * `{ ok: false, code: "semantic_disabled" }` WITHOUT reading source,
+ * calling the provider, or writing a vector (gate-off parity test covers
+ * this). The gate is checked at this single chokepoint — callers never
+ * need to re-check.
+ *
+ * Rule 44: vectors are written only for symbols that persisted
+ * successfully. The indexer reads nodes from the store (which only
+ * contains persisted nodes), so a `parse_failed` file contributes zero
+ * nodes and thus zero vectors.
+ *
+ * Rule 37: cache invalidation. When a symbol's canonical text changes,
+ * its content_hash changes, the cached row no longer matches, and the
+ * vector is re-embedded. The old vector is overwritten (ON CONFLICT
+ * UPDATE). Any SIMILAR_TO edge derived from the old vector is recomputed
+ * by the similarity pipeline on its next run.
+ */
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import type { HostEmbeddingProvider } from "@remnic/core/host-embedding-provider";
+import { normalizeHostEmbeddingVector } from "@remnic/core/host-embedding-provider";
+
+import type { GraphStore } from "../graph-store.js";
+import { buildCanonicalTextAndHash } from "./canonical-text.js";
+import type { SemanticConfig } from "./config.js";
+import type { IndexVectorsResult, SemanticFailure } from "./types.js";
+
+/**
+ * Input to {@link indexSymbolVectors}. The store provides node metadata +
+ * the vectors table; the provider embeds; repoRoot resolves file paths.
+ */
+export interface IndexVectorsInput {
+  readonly store: GraphStore;
+  readonly provider: HostEmbeddingProvider | undefined;
+  readonly repoRoot: string;
+  readonly config: SemanticConfig;
+  /**
+   * Optional abort signal forwarded to the provider. The indexer does not
+   * impose its own timeout (the provider's embed() contract handles that).
+   */
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * The model id used for cache keying. Derives from the provider's `model`
+ * (falling back to `id`) so a provider/model swap produces a distinct
+ * cache namespace and does not overwrite the prior vectors.
+ */
+export function modelIdFor(provider: HostEmbeddingProvider): string {
+  return provider.model ?? provider.id;
+}
+
+/**
+ * Index symbol vectors for every persisted node in the store.
+ *
+ * Flow:
+ *   1. Gate: if !config.enabled → tagged semantic_disabled (no work).
+ *   2. Provider check: if no provider → tagged provider_unavailable.
+ *   3. Read all nodes from the store (persisted only — rule 44).
+ *   4. For each node (within maxSymbolsPerRun budget):
+ *      a. Read source text from disk.
+ *      b. Build canonical text + hash.
+ *      c. Cache check: skip if cached row's content_hash matches.
+ *      d. Embed via provider.
+ *      e. Normalize (reject malformed → counted as skipped).
+ *      f. Persist vector.
+ *   5. Return counts.
+ *
+ * Budget order (rule 27): recently-changed symbols first. The store's
+ * readNodesForSemantic returns nodes ordered by qualified_name; the
+ * indexer applies the caller-supplied priority before slicing. When no
+ * priority is given, all nodes are eligible (budget 0 = unlimited).
+ */
+export async function indexSymbolVectors(
+  input: IndexVectorsInput,
+): Promise<IndexVectorsResult | SemanticFailure> {
+  const { store, provider, repoRoot, config, signal } = input;
+
+  // Closed store is a distinct degradation (rule 34) — do not treat it as
+  // an empty graph that returns { ok: true } with zero counts (cursor
+  // Bugbot: 'Closed store reports success').
+  if (store.isClosed) {
+    return { ok: false, code: "store_closed" };
+  }
+
+  // Rule 30/48 + rule 39: single gate chokepoint.
+  if (!config.enabled) {
+    return { ok: false, code: "semantic_disabled" };
+  }
+  if (!provider) {
+    return { ok: false, code: "provider_unavailable" };
+  }
+
+  const modelId = modelIdFor(provider);
+  // Wrap the store read so a transient SQLite error (SQLITE_BUSY / CORRUPT)
+  // maps to a tagged db_error instead of escaping indexSymbolVectors (#1680).
+  let nodes: readonly ReturnType<typeof store.readNodesForSemantic>[number][];
+  try {
+    nodes = store.readNodesForSemantic();
+  } catch {
+    return { ok: false, code: "db_error" };
+  }
+  // Budget applies to EMBED WORK, not the candidate list. Slicing the
+  // full node list (ordered by qualified_name) BEFORE the cache check
+  // meant a bounded run kept re-visiting the cached alphabetical prefix
+  // and never reached uncached or changed symbols later in the list, so
+  // a bounded semantic index could remain permanently incomplete. Now
+  // every node gets a cache check and only a successful embed consumes
+  // budget, so progress accumulates across runs until every symbol is
+  // embedded (cursor Bugbot: 'Embedding budget uses alphabetical order';
+  // chatgpt-codex-connector P2: 'Apply vector budget after skipping
+  // cached rows'). maxSymbolsPerRun=0 means unlimited.
+  const limit = config.maxSymbolsPerRun;
+
+  let embedded = 0;
+  let cached = 0;
+  let skipped = 0;
+  // Budget bounds provider CALLS (cost), not successful writes. A degraded
+  // provider that throws / returns null / returns a malformed vector for
+  // many uncached symbols must not bypass the per-run cost cap by never
+  // incrementing `embedded` (chatgpt-codex-connector: 'Count failed embed
+  // attempts against the vector budget'). Cached rows do not consume
+  // budget (no provider call); source-read failures do not either.
+  let embedAttempts = 0;
+
+  for (const node of nodes) {
+    if (signal?.aborted) break;
+    if (limit > 0 && embedAttempts >= limit) break;
+    // Read source text from disk.
+    const absolutePath = path.resolve(repoRoot, node.filePath);
+    let bytes: Buffer;
+    try {
+      bytes = await readFile(absolutePath);
+    } catch {
+      skipped += 1;
+      continue;
+    }
+    const start = Math.max(0, node.startByte);
+    const end = Math.min(bytes.length, node.endByte);
+    if (start > end) {
+      skipped += 1;
+      continue;
+    }
+    const rawText = bytes.subarray(start, end).toString("utf8");
+
+    // Canonical text + hash (rule 23/37). The embedded string MUST equal
+    // the hashed string (rule 23 — one form everywhere).
+    const { text: canonicalText, hash } = buildCanonicalTextAndHash({
+      symbol: {
+        kind: node.kind as never,
+        name: node.qualifiedName.split(/[.#:]/).pop() ?? node.qualifiedName,
+        qualifiedName: node.qualifiedName,
+        span: { startByte: node.startByte, endByte: node.endByte },
+      },
+      rawText,
+      maxBodyLines: config.canonicalBodyLines,
+    });
+
+    // Cache check: skip re-embed when content_hash matches AND the stored
+    // dims still equal the active provider's declared dimensions. A model
+    // that keeps the same model_id but changes vector size would otherwise
+    // leave stale-dimensionality rows cached (cursor Bugbot: 'Cache ignores
+    // embedding dimension changes'). When the provider does not declare
+    // dimensions (optional), the dims gate is skipped so caching still
+    // works instead of re-embedding every run (cursor Bugbot: 'Cache misses
+    // without provider dimensions').
+    const cachedRow = store.readSymbolVector(node.nodeId, modelId);
+    if (
+      cachedRow &&
+      cachedRow.contentHash === hash &&
+      (provider.dimensions === undefined || cachedRow.dims === provider.dimensions)
+    ) {
+      cached += 1;
+      continue;
+    }
+
+    // Count the embed attempt (cost) BEFORE the call, regardless of
+    // outcome, so a failed/null/malformed result still consumes budget.
+    embedAttempts += 1;
+    // Embed the CANONICAL text (not the raw span) so the vector
+    // corresponds to the content_hash that gates cache hits (rule 23).
+    // This also respects canonicalBodyLines as a cost/privacy bound.
+    let raw: ArrayLike<number> | null;
+    try {
+      raw = await provider.embed(canonicalText, {
+        signal,
+        inputType: "document",
+      });
+    } catch {
+      // Stale vector cleanup (rule 37): if a prior vector exists with a
+      // different content_hash and we cannot re-embed, delete the stale
+      // row so semantic_query/cosine confirmation do not serve it.
+      if (cachedRow && cachedRow.contentHash !== hash) {
+        await store.deleteSymbolVectors([node.nodeId]);
+      }
+      skipped += 1;
+      continue;
+    }
+    const vec = normalizeHostEmbeddingVector(raw);
+    if (!vec || vec.length === 0) {
+      if (cachedRow && cachedRow.contentHash !== hash) {
+        await store.deleteSymbolVectors([node.nodeId]);
+      }
+      skipped += 1;
+      continue;
+    }
+    const float32 = new Float32Array(vec);
+    // Only count a persisted embed — writeSymbolVector returns false (and
+    // is a no-op) when the store is closing/closed, so progress reporting
+    // must not claim an embedding that was dropped (cursor Bugbot: 'Embedded
+    // count after dropped writes').
+    const persisted = await store.writeSymbolVector({
+      nodeId: node.nodeId,
+      modelId,
+      contentHash: hash,
+      dims: float32.length,
+      vector: float32,
+    });
+    if (persisted) {
+      embedded += 1;
+    } else {
+      skipped += 1;
+    }
+  }
+
+  return { ok: true, embedded, cached, skipped };
+}