sweet-search 2.5.2 → 2.5.3

package/core/incremental-indexing/domain/chunk-identity.mjs

@@ -0,0 +1,260 @@
+/**
+ * Stable AST-structural chunk identity.
+ *
+ * Plan § 7.2 makes the positional `chunk_id` from `ast-chunker.js` the
+ * single biggest defeat of incremental encode-skip: inserting one
+ * function at the top of a file shifts every downstream `parentCounter`
+ * → every chunk ID changes → cache-miss on every chunk → projected 10×
+ * CPU saving collapses to 0. The fix is a content-anchored identity that
+ * survives whitespace edits, import shuffles, and insertions.
+ *
+ * Two regimes:
+ *
+ * 1. **Symbol-attached chunks** (functions, methods, classes, structs,
+ *    etc.). The identity binds to the containing symbol path plus the
+ *    whitespace-normalised signature line:
+ *
+ *        struct_id = hash(file_path || parent_symbol_path || symbol_name || signature_norm)
+ *
+ *    Renaming the function flips the ID for the renamed chunk only.
+ *    Reordering siblings, inserting a new function above, or
+ *    re-indenting the file is invisible.
+ *
+ * 2. **Anonymous chunks** (file headers, JSX blocks, free-form
+ *    statements, regex-split sub-chunks). The identity binds to a
+ *    rolling hash of normalised content under the parent symbol path,
+ *    PLUS a mandatory `occurrence_index_in_parent` suffix:
+ *
+ *        struct_id = hash(file_path || parent_symbol_path || rolling_hash) || '_' || occurrence_index
+ *
+ *    The occurrence index is the *count of preceding siblings with the
+ *    same `(rolling_hash, parent_symbol_path)` tuple* — not the absolute
+ *    sibling index. This guarantees that two distinct sibling chunks
+ *    keep distinct IDs even when they sit between identical pairs, and
+ *    that two identical siblings keep distinct IDs because their
+ *    occurrence-in-population is different (`_0`, `_1`, ...). See plan
+ *    § 7.2 "occurrence index ... is mandatory" and § 33 unit-test
+ *    coverage requirements for the renamed-one-of-two case.
+ *
+ * Fallback: parser failure or no AST metadata → use the existing
+ * positional `chunk_id` and set `structural = false`. Downstream
+ * dedup paths still hash the chunk content, so the worst-case is no
+ * structural savings for that one chunk.
+ *
+ * This module is pure domain logic. It must not import the chunker,
+ * SQLite, the encoder pool, or any infrastructure adapter.
+ */
+
+import { contentHashSync } from '../infrastructure/hashing.mjs';
+
+/**
+ * Normalise whitespace in a signature for hashing. Collapses runs of
+ * whitespace into a single space, trims the result, and drops trailing
+ * `=> {` / `{` braces so e.g.
+ *   `async function foo (a , b ) {`
+ *   `async function foo(a, b) {`
+ * hash identically.
+ *
+ * @param {string} signature
+ * @returns {string}
+ */
+export function normalizeSignature(signature) {
+  if (typeof signature !== 'string') return '';
+  return signature
+    .replace(/[\s ]+/g, ' ')
+    .replace(/\s*\{\s*$/, '')
+    .replace(/\s*([(),:;<>=\[\]])\s*/g, '$1')
+    .trim();
+}
+
+/**
+ * Normalise an anonymous chunk's content for rolling-hash purposes.
+ * Drops leading/trailing whitespace, collapses internal whitespace runs,
+ * and removes blank lines so format-on-save edits cancel.
+ *
+ * Intentionally does NOT strip comments — comment edits should change
+ * the encoder input and therefore the dense embedding, but they do not
+ * change the chunk's identity in v1 unless the chunker drops them in a
+ * subsequent pass.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+export function normalizeAnonymousContent(content) {
+  if (typeof content !== 'string') return '';
+  // 1. Collapse internal runs of whitespace (preserving newlines so the
+  //    rolling hash still distinguishes multi-line forms from one-line
+  //    forms).
+  // 2. Drop blank lines so format-on-save reflows are invisible.
+  // 3. Trim leading/trailing whitespace overall.
+  const collapsed = content.replace(/[ \t]+/g, ' ');
+  const noBlanks = collapsed.split('\n').map((line) => line.trim()).filter(Boolean).join('\n');
+  return noBlanks;
+}
+
+/**
+ * Build the parent-symbol path string used in both regimes. The chunker
+ * may already provide `parent_symbol` and `parent_type`; we serialise
+ * them as `type:name` and join with `/` for any hierarchy ancestors so
+ * `Foo.bar.baz` and `module:Foo / class:Foo / method:bar / lambda:baz`
+ * survive sibling-rename without collision.
+ *
+ * Accepted shapes:
+ *   - `chunk.metadata.parent_path` — pre-joined `/`-separated string
+ *   - `chunk.metadata.parent_symbol` plus `chunk.metadata.parent_type`
+ *   - undefined → empty string (top-level)
+ *
+ * @param {object} metadata
+ * @returns {string}
+ */
+export function parentSymbolPath(metadata) {
+  if (!metadata) return '';
+  if (typeof metadata.parent_path === 'string' && metadata.parent_path.length > 0) {
+    return metadata.parent_path;
+  }
+  const parent = metadata.parent_symbol;
+  const parentType = metadata.parent_type;
+  if (parent && parentType) return `${parentType}:${parent}`;
+  if (parent) return `:${parent}`;
+  return '';
+}
+
+/**
+ * Determine whether a chunk is symbol-attached for identity purposes.
+ *
+ * @param {object} chunk
+ * @returns {boolean}
+ */
+export function isSymbolAttached(chunk) {
+  if (!chunk || !chunk.metadata) return false;
+  const symbol = chunk.metadata.symbol;
+  const chunkType = chunk.metadata.chunk_type;
+  if (!symbol || symbol === 'unknown' || symbol === 'code') return false;
+  if (!chunkType) return false;
+  // Treat anything that names a callable / class / module as symbol-
+  // attached. The chunker emits chunk_type values like 'function',
+  // 'method', 'class', 'struct', 'interface', 'enum', 'module',
+  // 'namespace', plus 'code'/'plain'/'doc' for non-symbol chunks.
+  return chunkType !== 'code' && chunkType !== 'plain' && chunkType !== 'doc' && chunkType !== 'text';
+}
+
+/**
+ * Compute the rolling content hash used by anonymous chunk identity.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+export function rollingContentHash(content) {
+  return contentHashSync(normalizeAnonymousContent(content));
+}
+
+/**
+ * Derive a stable structural ID for a single chunk.
+ *
+ * Returns:
+ *   {
+ *     chunkStructId: string,
+ *     structural: boolean,
+ *     rollingHash: string | null,
+ *     reason: 'symbol' | 'anonymous' | 'fallback',
+ *   }
+ *
+ * Callers MUST provide the occurrence index when `structural=true` and
+ * `reason='anonymous'`; the convenience wrapper
+ * `assignStructuralIds(chunks, filePath)` below computes the indices in
+ * a single pass and is the recommended entry point.
+ *
+ * @param {object} chunk
+ * @param {string} filePath
+ * @param {number|null} occurrenceIndex  Mandatory for anonymous chunks.
+ * @returns {{chunkStructId:string, structural:boolean, rollingHash:string|null, reason:'symbol'|'anonymous'|'fallback'}}
+ */
+export function deriveStructuralId(chunk, filePath, occurrenceIndex) {
+  if (!chunk || typeof filePath !== 'string') {
+    return { chunkStructId: '', structural: false, rollingHash: null, reason: 'fallback' };
+  }
+  const metadata = chunk.metadata || {};
+  const parentPath = parentSymbolPath(metadata);
+
+  if (isSymbolAttached(chunk)) {
+    const signature = metadata.signature || metadata.symbol_signature || '';
+    const sigNorm = normalizeSignature(signature);
+    const sigSource = sigNorm.length > 0 ? sigNorm : `${metadata.chunk_type || ''}:${metadata.symbol || ''}`;
+    const id = contentHashSync(
+      `${filePath}\0${parentPath}\0${metadata.symbol}\0${sigSource}`,
+    );
+    return {
+      chunkStructId: id,
+      structural: true,
+      rollingHash: null,
+      reason: 'symbol',
+    };
+  }
+
+  // Anonymous regime.
+  if (occurrenceIndex == null || !Number.isFinite(occurrenceIndex) || occurrenceIndex < 0) {
+    // Per plan § 7.2, an anonymous chunk without an occurrence index is a
+    // bug at the call site, NOT a fallback opportunity. The wrapper below
+    // always supplies one; callers reaching this branch directly are
+    // misusing the API.
+    return { chunkStructId: '', structural: false, rollingHash: null, reason: 'fallback' };
+  }
+  const text = chunk.content || chunk.text || '';
+  const rolling = rollingContentHash(text);
+  const id =
+    contentHashSync(`${filePath}\0${parentPath}\0${rolling}`) + '_' + occurrenceIndex;
+  return {
+    chunkStructId: id,
+    structural: true,
+    rollingHash: rolling,
+    reason: 'anonymous',
+  };
+}
+
+/**
+ * Assign stable structural IDs across an ordered chunk list for one file.
+ *
+ * Pass order:
+ *   1. First pass: classify each chunk as symbol-attached / anonymous,
+ *      compute rolling hashes for anonymous chunks.
+ *   2. Second pass: number anonymous chunks within each
+ *      `(parent_path, rolling_hash)` population (occurrence_index_in_parent).
+ *   3. Emit a parallel array of structural-id records aligned with the
+ *      input chunk list.
+ *
+ * Mutating the input chunks is intentionally avoided here; the caller
+ * decides whether to write the IDs onto chunks, into a SQL transaction,
+ * or both.
+ *
+ * @param {Array<object>} chunks
+ * @param {string} filePath
+ * @returns {Array<{chunkStructId:string, structural:boolean, rollingHash:string|null, reason:'symbol'|'anonymous'|'fallback', occurrenceIndex:number|null}>}
+ */
+export function assignStructuralIds(chunks, filePath) {
+  if (!Array.isArray(chunks)) return [];
+  const out = new Array(chunks.length);
+  const populationCount = new Map();
+
+  for (let i = 0; i < chunks.length; i++) {
+    const chunk = chunks[i];
+    if (isSymbolAttached(chunk)) {
+      const derived = deriveStructuralId(chunk, filePath, null);
+      out[i] = { ...derived, occurrenceIndex: null };
+      continue;
+    }
+    // Anonymous chunk: compute population key, occurrence index, then derive.
+    const parentPath = parentSymbolPath(chunk?.metadata || {});
+    const text = chunk?.content || chunk?.text || '';
+    const rolling = rollingContentHash(text);
+    const key = `${parentPath}\0${rolling}`;
+    const idx = populationCount.get(key) || 0;
+    populationCount.set(key, idx + 1);
+
+    const derived = deriveStructuralId(chunk, filePath, idx);
+    out[i] = { ...derived, occurrenceIndex: idx };
+  }
+
+  return out;
+}
+
+export const __testing = { isSymbolAttached, parentSymbolPath, normalizeSignature, normalizeAnonymousContent };

package/core/incremental-indexing/domain/encoder-deps.mjs

@@ -0,0 +1,193 @@
+/**
+ * Encoder-input dependency registry.
+ *
+ * Plan § 7.2.1, § 12.4. The encoder-input hashes in
+ * `encoder-input.mjs` answer the question "given the fully built
+ * `embedding_text` / `li_text`, do I still need to encode this chunk?"
+ * They do **not** answer "which chunks need their `embedding_text`
+ * rebuilt when something outside the chunk body changes?"
+ *
+ * Today, the production policy keeps cross-file metadata out of encoder
+ * inputs: changing file A's callee body does not re-embed unchanged caller
+ * file B. But the chunker DOES inject same-file scope / defines / uses
+ * enrichment plus import names into `embedding_text`. When any of those
+ * facts changes for a stable chunk, the reconciler must:
+ *
+ *   1. Mark the chunk **metadata-dirty**.
+ *   2. Re-run graph enrichment for that chunk to rebuild `embedding_text`
+ *      / `li_text` / `li_greedy_text`.
+ *   3. Compute the exact input hash and reuse the previous payload only
+ *      on byte-identical match.
+ *
+ * The registry is a small key→consumer table seeded by the reconcile
+ * tick whenever a chunk is encoded. When a key fires (e.g. a same-file
+ * scope change), the registry yields every dependent chunk so they can
+ * be added to the dirty set.
+ *
+ * Dependency-key vocabulary (all string keys; readers should treat them
+ * opaquely):
+ *
+ *   * `path:<relative_path>`            — file-level identity facts.
+ *   * `lang:<relative_path>`            — language detection result for the file.
+ *   * `chunk-type:<relative_path>`      — chunk kind selected by the chunker.
+ *   * `symbol:<relative_path>`          — primary chunk symbol metadata.
+ *   * `signature:<relative_path>`       — AST signature metadata.
+ *   * `additional-symbols:<relative_path>` — sibling symbols injected into text.
+ *   * `policy:embed:<n>`                — bumps when embed-text policy changes.
+ *   * `policy:li:<n>`                   — bumps when LI input policy changes.
+ *   * `parent:<relative_path>:<parent>` — same-file parent symbol identity.
+ *   * `same-file-symbols:<relative_path>` — set of symbols defined in this file.
+ *   * `same-file-imports:<relative_path>` — set of import target names in this file.
+ *   * `same-file-scope:<relative_path>` — same-file scope/defines/uses enrichment.
+ *   * `dedup-cluster:<cluster_id>`      — dedup cluster membership.
+ *   * `dedup-exemplar:<exemplar_id>`    — dedup alias target.
+ *   * `entity:<entity_id>`              — future cross-file rule (plan § 7.2.1).
+ *   * `relationship:<source_entity_id>` — future cross-file rule.
+ *   * `file-exports:<relative_path>`    — future cross-file rule.
+ *   * `graph-centrality:<entity_id>`    — future cross-file rule.
+ *
+ * Consumers (`consumer` column of `encoder_input_dependencies`):
+ *
+ *   * `dense` — affects `embedding_text` only.
+ *   * `li`    — affects `pickLiInput` only.
+ *   * `dedup` — affects dedup signals.
+ *
+ * The same chunk can register multiple `(key, consumer)` pairs.
+ */
+
+import {
+  DEDUP_INPUT_POLICY_VERSION,
+  EMBED_TEXT_POLICY_VERSION,
+  LI_INPUT_POLICY_VERSION,
+} from './encoder-input.mjs';
+
+const MAX_DEPENDENCY_KEYS_PER_QUERY = 900;
+
+/**
+ * Build the same-file dependency set for a single chunk. The reconcile
+ * tick calls this **after** graph enrichment so the inputs already
+ * reflect the current scope / defines / uses lines.
+ *
+ * @param {object} chunk             Enriched chunk (post graph-enrichment).
+ * @returns {Array<{dependency_key: string, consumer: 'dense'|'li'|'dedup'}>}
+ */
+export function collectChunkDependencies(chunk) {
+  if (!chunk) return [];
+  const meta = chunk.metadata || {};
+  const rel = meta.relative_path || meta.path || meta.file_path || chunk.file || meta.file || '';
+  const parent = meta.parent_symbol || '';
+  const parentType = meta.parent_type || '';
+  const clusterId = meta.clusterId || '';
+  const exemplarId = meta.exemplarId || '';
+  const deps = [];
+  const push = (dependencyKey, consumers) => {
+    for (const consumer of consumers) {
+      deps.push({ dependency_key: dependencyKey, consumer });
+    }
+  };
+
+  if (rel) {
+    const encoderConsumers = ['dense', 'li'];
+    push(`path:${rel}`, encoderConsumers);
+    push(`lang:${rel}`, encoderConsumers);
+    push(`chunk-type:${rel}`, encoderConsumers);
+    push(`symbol:${rel}`, encoderConsumers);
+    push(`signature:${rel}`, encoderConsumers);
+    push(`additional-symbols:${rel}`, encoderConsumers);
+    push(`same-file-symbols:${rel}`, encoderConsumers);
+    push(`same-file-imports:${rel}`, encoderConsumers);
+    push(`same-file-scope:${rel}`, encoderConsumers);
+  }
+  if (parent && rel) {
+    push(`parent:${rel}:${parent}`, ['dense', 'li']);
+  }
+  if (parentType && rel) {
+    push(`parent-type:${rel}:${parentType}`, ['dense', 'li']);
+  }
+  if (clusterId) {
+    deps.push({ dependency_key: `dedup-cluster:${clusterId}`, consumer: 'dedup' });
+  }
+  if (exemplarId) {
+    deps.push({ dependency_key: `dedup-exemplar:${exemplarId}`, consumer: 'dedup' });
+  }
+  if (Object.hasOwn(meta, 'liReuseEligible')) {
+    const key = clusterId ? `dedup-li-reuse:${clusterId}` : 'dedup-li-reuse';
+    deps.push({ dependency_key: key, consumer: 'dedup' });
+  }
+  // Policy fingerprints. Any consumer of these keys is the canonical place
+  // to invalidate cached encoder payloads after a policy bump.
+  deps.push({ dependency_key: `policy:embed:${EMBED_TEXT_POLICY_VERSION}`, consumer: 'dense' });
+  deps.push({ dependency_key: `policy:li:${LI_INPUT_POLICY_VERSION}`, consumer: 'li' });
+  deps.push({ dependency_key: `policy:dedup:${DEDUP_INPUT_POLICY_VERSION}`, consumer: 'dedup' });
+
+  return deps;
+}
+
+/**
+ * Persist the dependency set for a chunk into the
+ * `encoder_input_dependencies` table. Caller controls the transaction.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} filePath
+ * @param {string} chunkStructId
+ * @param {Array<{dependency_key:string, consumer:string}>} deps
+ */
+export function persistDependencies(db, filePath, chunkStructId, deps) {
+  if (!chunkStructId) return;
+  const remove = db.prepare(`
+    DELETE FROM encoder_input_dependencies
+    WHERE file_path = ? AND chunk_struct_id = ?
+  `);
+  const insert = db.prepare(`
+    INSERT OR IGNORE INTO encoder_input_dependencies
+      (dependency_key, file_path, chunk_struct_id, consumer)
+    VALUES (?, ?, ?, ?)
+  `);
+  remove.run(filePath, chunkStructId);
+  for (const dep of deps) {
+    insert.run(dep.dependency_key, filePath, chunkStructId, dep.consumer);
+  }
+}
+
+/**
+ * Look up dependent chunks for a list of changed dependency keys. The
+ * reconciler uses this to expand the metadata-dirty set when external
+ * facts change.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {string[]} keys
+ * @returns {Array<{file_path:string, chunk_struct_id:string, consumer:string}>}
+ */
+export function dependentsOf(db, keys) {
+  if (!Array.isArray(keys) || keys.length === 0) return [];
+  const out = [];
+  const seen = new Set();
+  for (let i = 0; i < keys.length; i += MAX_DEPENDENCY_KEYS_PER_QUERY) {
+    const batch = keys.slice(i, i + MAX_DEPENDENCY_KEYS_PER_QUERY);
+    const placeholders = batch.map(() => '?').join(',');
+    const rows = db.prepare(`
+      SELECT DISTINCT file_path, chunk_struct_id, consumer
+      FROM encoder_input_dependencies
+      WHERE dependency_key IN (${placeholders})
+      ORDER BY file_path, chunk_struct_id, consumer
+    `).all(...batch);
+    for (const row of rows) {
+      const key = `${row.file_path}\0${row.chunk_struct_id}\0${row.consumer}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push(row);
+    }
+  }
+  return out;
+}
+
+/**
+ * Drop all dependency rows for a file. Used when a file is deleted or its
+ * structural identity has been replaced wholesale.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} filePath
+ */
+export function forgetFile(db, filePath) {
+  db.prepare('DELETE FROM encoder_input_dependencies WHERE file_path = ?').run(filePath);
+}

package/core/incremental-indexing/domain/encoder-input.mjs

@@ -0,0 +1,225 @@
+/**
+ * Exact encoder-input hashes for the dense, LI, and dedup consumers.
+ *
+ * Plan § 7.2 + § 7.2.1 + § 12.4. The reconcile path must reuse a previously
+ * computed dense embedding only when the **exact bytes** sent to the encoder
+ * have not changed. The "bytes" depend on far more than the raw chunk body:
+ *
+ *   * Dense (`embedding_text`):
+ *       - chunk body
+ *       - relative path, language, chunk type, primary symbol
+ *       - parent symbol + parent type
+ *       - AST signature (when the active variant uses signatures)
+ *       - sibling `additional_symbols`
+ *       - active embedding-text policy fingerprint
+ *       - same-file scope / defines / uses enrichment
+ *
+ *   * Late-interaction (`pickLiInput`):
+ *       - same body
+ *       - language-routed input variant (Python and Java-family use
+ *         `li_text`; JS/TS/etc. use the greedy form)
+ *       - LI input policy fingerprint
+ *
+ *   * Dedup (`simhash` / `clusterId` / `exemplarId` / `liReuseEligible`):
+ *       - chunk content normalised for dedup
+ *       - cluster exemplar identity (a member whose exemplar changed is
+ *         "dedup-dirty" even if its own content is stable)
+ *
+ * This module is pure domain logic. It accepts plain JS objects and returns
+ * 16-hex-char hash strings. The Phase 1 reconciler calls these helpers
+ * **after** the existing graph-enrichment pass has built `embedding_text` /
+ * `li_text` / `li_greedy_text` on each chunk, so the inputs to the hashers
+ * are already metadata-aware.
+ */
+
+import { contentHashSync, stableStringify, metadataFingerprint } from '../infrastructure/hashing.mjs';
+
+/**
+ * Policy fingerprint constants. Bump these when the encoder-text recipe
+ * changes in a way that invalidates cached payloads. The values are
+ * intentionally simple integers; reconcile mixes them into the hash inputs
+ * so changing the variant flushes the cache without renaming columns.
+ *
+ * EMBED_TEXT_POLICY_VERSION mirrors the cold-path `pipelineVersion` bump in
+ * `core/indexing/incremental-tracker.js::buildConfigFingerprint`; LI policy
+ * has its own counter because LI input routing can change independently of
+ * dense input.
+ */
+export const EMBED_TEXT_POLICY_VERSION = 1;
+export const LI_INPUT_POLICY_VERSION = 1;
+export const DEDUP_INPUT_POLICY_VERSION = 1;
+
+/**
+ * Language taxonomy used by `pickLiInput`. The reconcile path mirrors the
+ * production helper at `core/indexing/indexer-ann.js`; we keep a local
+ * mirror so the incremental domain logic remains dependency-light. Any
+ * change to the production taxonomy must update this table AND bump
+ * LI_INPUT_POLICY_VERSION.
+ */
+const LI_TEXT_LANGS = new Set(['python', 'java', 'php', 'csharp', 'c#', 'kotlin', 'scala']);
+// Everything else (JS/TS/JSX/TSX, Ruby, Go, C/C++/Rust, unknown) uses
+// li_greedy_text → embedding_text → li_text.
+
+/**
+ * Normalise a path for the LI Java-family slug. This mirrors
+ * `core/indexing/ast-chunker.js::normalizePathSlug`: strip only the
+ * trailing generated `_<hex>` suffix before the extension.
+ *
+ * @param {string} relativePath
+ */
+export function normalizePathSlug(relativePath) {
+  if (!relativePath) return relativePath;
+  return String(relativePath).replace(/_[0-9a-f]{6,}(\.[a-zA-Z0-9]+)$/, '$1');
+}
+
+/**
+ * Return the LI input text for a chunk per the language taxonomy. Mirrors
+ * `pickLiInput()` in `core/indexing/indexer-ann.js`.
+ *
+ * @param {object} chunk     Enriched chunk with `metadata.language`,
+ *                            `metadata.relative_path`, `li_text`,
+ *                            `li_greedy_text`, `embedding_text`.
+ * @returns {string}
+ */
+export function pickLiInputText(chunk) {
+  if (!chunk) return '';
+  const meta = chunk.metadata || {};
+  const language = meta.language;
+  const liText = chunk.li_text || '';
+  const liGreedy = chunk.li_greedy_text || '';
+  const embedText = chunk.embedding_text || chunk.text || chunk.content || '';
+
+  if (LI_TEXT_LANGS.has(language)) {
+    // Python omits the path line and Java-family slug-stripping happens
+    // when the chunker builds `li_text`; the hasher must not reconstruct
+    // a second, different policy here.
+    return liText || embedText;
+  }
+  // Default route: li_greedy_text → embedding_text → li_text.
+  return liGreedy || embedText || liText;
+}
+
+/**
+ * Compute the dense `embedding_input_hash`. The input is the exact
+ * `embedding_text` produced by the chunker + graph-enrichment pass, mixed
+ * with the policy fingerprint.
+ *
+ * @param {object} chunk
+ * @returns {string}
+ */
+export function denseInputHash(chunk) {
+  if (!chunk) return '';
+  const text = chunk.embedding_text || chunk.text || chunk.content || '';
+  return contentHashSync(`${text}|policy:${EMBED_TEXT_POLICY_VERSION}`);
+}
+
+/**
+ * Compute the LI `li_input_hash`. Resolves the LI input text via the
+ * language taxonomy and mixes the policy fingerprint.
+ *
+ * @param {object} chunk
+ * @returns {string}
+ */
+export function liInputHash(chunk) {
+  if (!chunk) return '';
+  const text = pickLiInputText(chunk);
+  return contentHashSync(`${text}|policy:${LI_INPUT_POLICY_VERSION}`);
+}
+
+/**
+ * Compute the dedup `metadata_fingerprint`. Plan § 7.2.1 calls this out as
+ * its own consumer so that a member whose cluster exemplar changed gets
+ * re-aliased even when its own `embedding_input_hash` / `li_input_hash`
+ * are unchanged.
+ *
+ * Dedup signal taxonomy:
+ *   - `simhash` (chunk-local; recomputed when content changes)
+ *   - `clusterId` (cluster membership)
+ *   - `exemplarId` (target of the alias)
+ *   - `isExemplar` (whether this row is the exemplar)
+ *   - `aliasJaccard` (similarity score; informational)
+ *   - `liReuseEligible` (drives the LI-side alias decision)
+ *
+ * The fingerprint is built from a stable JSON of these fields plus the
+ * policy version.
+ *
+ * @param {object} chunk
+ * @returns {string}
+ */
+export function dedupFingerprint(chunk) {
+  const meta = (chunk && chunk.metadata) || {};
+  return contentHashSync(stableStringify({
+    simhash: meta.simhash ?? null,
+    clusterId: meta.clusterId ?? null,
+    exemplarId: meta.exemplarId ?? null,
+    isExemplar: meta.isExemplar ?? null,
+    aliasJaccard: meta.aliasJaccard ?? null,
+    liReuseEligible: meta.liReuseEligible ?? null,
+    policy: DEDUP_INPUT_POLICY_VERSION,
+  }));
+}
+
+function chunkRelativePath(chunk, meta = chunk?.metadata || {}) {
+  return firstSafeRelativePath(
+    meta.relative_path,
+    meta.path,
+    meta.file_path,
+    chunk?.file,
+    meta.file,
+  );
+}
+
+function firstSafeRelativePath(...candidates) {
+  for (const candidate of candidates) {
+    if (typeof candidate !== 'string') continue;
+    const normalized = candidate.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+/g, '/');
+    if (!normalized || normalized === '.' || normalized.startsWith('/')) continue;
+    if (/^[A-Za-z]:\//.test(normalized)) continue;
+    if (normalized === '..' || normalized.startsWith('../') || normalized.includes('/../')) continue;
+    return normalized;
+  }
+  return null;
+}
+
+/**
+ * Convenience: compute all three hashes plus the raw `chunk_text_hash` and
+ * `metadata_fingerprint` in one pass.
+ *
+ * The returned `metadata_fingerprint` here is the "encoder-input-affecting
+ * metadata hash" required by plan § 7.2 / § 33 for the `metadata_fingerprint`
+ * column. It is distinct from the dedup `dedupFingerprint`; both must be
+ * stored when the reconcile path lands the row (the dedup fingerprint is
+ * carried inside the encoder-input dependency registry; see
+ * `core/incremental-indexing/domain/encoder-deps.mjs`).
+ *
+ * @param {object} chunk
+ * @returns {{chunk_text_hash:string, embedding_input_hash:string, li_input_hash:string, metadata_fingerprint:string, dedup_fingerprint:string}}
+ */
+export function chunkInputHashes(chunk) {
+  const text = chunk?.content || chunk?.text || '';
+  const meta = chunk?.metadata || {};
+  return {
+    chunk_text_hash: contentHashSync(text),
+    embedding_input_hash: denseInputHash(chunk),
+    li_input_hash: liInputHash(chunk),
+    metadata_fingerprint: contentHashSync(stableStringify({
+      relative_path: chunkRelativePath(chunk, meta),
+      language: meta.language ?? null,
+      chunk_type: meta.chunk_type ?? null,
+      symbol: meta.symbol ?? null,
+      parent_symbol: meta.parent_symbol ?? null,
+      parent_type: meta.parent_type ?? null,
+      signature: meta.signature ?? null,
+      additional_symbols: meta.additional_symbols ?? null,
+      policy_embed: EMBED_TEXT_POLICY_VERSION,
+      policy_li: LI_INPUT_POLICY_VERSION,
+    })),
+    dedup_fingerprint: dedupFingerprint(chunk),
+  };
+}
+
+/**
+ * Re-export metadataFingerprint for callers that want the generic stable-
+ * stringify hash without the encoder-specific field selection.
+ */
+export { metadataFingerprint };