@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/runtime/knowledge/code-corpus.js

@@ -0,0 +1,277 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+
+const CORPUS_LIMITS = Object.freeze({ maxFiles: 2000, maxFileBytes: 1024 * 1024, maxBytes: 64 * 1024 * 1024, timeoutMs: 2000, maxOutputBytes: 2 * 1024 * 1024 });
+const EXCLUDED = new Set(['.git', '.doflow', 'node_modules', 'graphify-out', '.semble', '__pycache__']);
+const compareText = (a        , b        )         => a < b ? -1 : a > b ? 1 : 0;
+const digest = (value     )         => crypto.createHash('sha256').update(value).digest('hex');
+
+function relativeCodePath(raw     )                {
+  if (typeof raw !== 'string' || !raw || raw.includes('\0') || /[\r\n]/.test(raw)) return null;
+  const rel = raw.replace(/\\/g, '/').replace(/^\.\//, '');
+  if (path.posix.isAbsolute(rel) || /^[A-Za-z]:/.test(rel) || rel.split('/').some((p        ) => p === '..' || p === '' || p === '.')) return null;
+  return rel;
+}
+
+function insideRoot(root        , absolute        )          {
+  const rel = path.relative(root, absolute);
+  return rel !== '' && !path.isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${path.sep}`);
+}
+
+function sameFile(a     , b     )          {
+  return a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs;
+}
+
+/** lstat every component under root, refusing a symlink; returns the final component's lstat or a refusal reason. */
+function statComponents(root        , pieces          , { fsImpl, now, deadline, verifiedDirs }     )      {
+  let cursor = root;
+  let stat      = null;
+  for (let i = 0; i < pieces.length; i += 1) {
+    if (now() > deadline) return 'deadline';
+    cursor = cursor.endsWith(path.sep) ? cursor + pieces[i] : cursor + path.sep + pieces[i]; // pieces are validated relativeCodePath segments
+    const directory = i < pieces.length - 1;
+    if (directory && verifiedDirs?.has(cursor)) continue;
+    stat = fsImpl.lstatSync(cursor);
+    if (stat.isSymbolicLink()) return 'symlink';
+    if (directory && verifiedDirs) verifiedDirs.add(cursor);
+  }
+  return stat;
+}
+
+/**
+ * Read a regular admitted path using a bounded descriptor, never an unbounded readFile.
+ * `verifiedDirs` is for one pass over a root the caller proved real: a directory already proven not to
+ * be a symlink is not re-proven, and the realpath checks become component checks (with no symlink
+ * component under a real root the path is its own realpath). The caller re-proves every directory in the
+ * set after its pass and drops what it read under one that changed (see searchCodeLexical).
+ * `hash: false` defers the digest to the caller, unless an admitted hash must be checked.
+ */
+function readCorpusFile(root        , entry     , { maxBytes = CORPUS_LIMITS.maxFileBytes, fsImpl = fs, now = Date.now, deadline = Infinity, hash = true, verifiedDirs = null }      = {})      {
+  let fd      = null;
+  let bytesRead = 0;
+  try {
+    const rel = relativeCodePath(entry?.path);
+    if (!rel) return { ok: false, reason: 'invalid-path', bytesRead };
+    const absolute = path.resolve(root, rel);
+    if (!insideRoot(root, absolute)) return { ok: false, reason: 'outside-root', bytesRead };
+    const pieces = rel.split('/');
+    const checked = statComponents(root, pieces, { fsImpl, now, deadline, verifiedDirs });
+    if (typeof checked === 'string') return { ok: false, reason: checked, bytesRead };
+    if (!verifiedDirs && fsImpl.realpathSync(absolute) !== absolute) return { ok: false, reason: 'outside-root', bytesRead };
+    const before = verifiedDirs ? checked : fsImpl.lstatSync(absolute);
+    if (!before.isFile()) return { ok: false, reason: 'not-regular-file', bytesRead };
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0 || before.size > maxBytes) return { ok: false, reason: 'read-byte-limit', bytesRead };
+    fd = fsImpl.openSync(absolute, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0) | (fs.constants.O_NONBLOCK || 0));
+    const opened = fsImpl.fstatSync(fd);
+    if (!opened.isFile() || !sameFile(before, opened)) return { ok: false, reason: 'source-changed', bytesRead };
+    const buffer = Buffer.alloc(Math.min(maxBytes + 1, opened.size + 1));
+    while (bytesRead < buffer.length) {
+      if (now() > deadline) return { ok: false, reason: 'deadline', bytesRead };
+      const count = fsImpl.readSync(fd, buffer, bytesRead, buffer.length - bytesRead, bytesRead);
+      if (!count) break;
+      bytesRead += count;
+    }
+    if (bytesRead > maxBytes) return { ok: false, reason: 'read-byte-limit', bytesRead };
+    const after = fsImpl.fstatSync(fd);
+    const contained = verifiedDirs ? true : fsImpl.realpathSync(absolute) === absolute;
+    if (!sameFile(opened, after) || !sameFile(after, fsImpl.lstatSync(absolute)) || !contained || bytesRead !== after.size) {
+      return { ok: false, reason: 'source-changed', bytesRead };
+    }
+    const content = buffer.subarray(0, bytesRead);
+    const fileHash = hash || entry.fileHash ? digest(content) : null;
+    if (entry.fileHash && entry.fileHash !== fileHash) return { ok: false, reason: 'source-changed', bytesRead };
+    return { ok: true, content, fileHash, bytesRead, stat: after };
+  } catch (error     ) {
+    return { ok: false, reason: error.code === 'ENOENT' ? 'missing-source' : 'source-unreadable', bytesRead };
+  } finally {
+    if (fd !== null) { try { fsImpl.closeSync(fd); } catch { /* no live descriptor survives */ } }
+  }
+}
+
+function globExpression(glob        )         {
+  let out = '';
+  for (let i = 0; i < glob.length; i += 1) {
+    const ch = glob[i];
+    if (ch === '*') {
+      if (glob[i + 1] === '*') {
+        i += 1;
+        if (glob[i + 1] === '/') { i += 1; out += '(?:.*/)?'; }
+        else out += '.*';
+      } else out += '[^/]*';
+    } else if (ch === '?') out += '[^/]';
+    else out += ch.replace(/[|\\{}()[\]^$+.]/g, '\\$&');
+  }
+  return out;
+}
+
+/** Normalize the scopes once per admission; a plain scope matches itself or any path under it. */
+function scopeMatcher(scopes       )                           {
+  if (!scopes.length) return () => true;
+  const plain = new Set        ();
+  const globs           = [];
+  for (const raw of scopes) {
+    if (typeof raw !== 'string') continue;
+    const scope = raw.replace(/^\.\//, '').replace(/\/$/, '');
+    if (!scope || scope === '.' || scope === '**') return () => true;
+    if (!/[?*]/.test(scope)) plain.add(scope);
+    else globs.push(new RegExp(`^${globExpression(scope)}$`));
+  }
+  return (rel        ) => {
+    if (plain.has(rel)) return true;
+    for (let i = rel.indexOf('/'); i > 0; i = rel.indexOf('/', i + 1)) if (plain.has(rel.slice(0, i))) return true;
+    return globs.some((glob) => glob.test(rel));
+  };
+}
+
+function parseIgnore(text        , base        )        {
+  const rules        = [];
+  for (let line of text.split(/\r?\n/)) {
+    line = line.replace(/(?<!\\) +$/, '');
+    if (!line || line.startsWith('#')) continue;
+    const negate = line.startsWith('!');
+    if (negate) line = line.slice(1);
+    line = line.replace(/^\\([#!])/, '$1');
+    const directory = line.endsWith('/');
+    if (directory) line = line.slice(0, -1);
+    const anchored = line.startsWith('/');
+    if (anchored) line = line.slice(1);
+    if (!line) continue;
+    const prefix = anchored || line.includes('/') ? '^' : '(?:^|/)';
+    rules.push({ base, negate, directory, regex: new RegExp(`${prefix}${globExpression(line)}(?:/.*)?$`) });
+  }
+  return rules;
+}
+
+function ignored(rel        , rules       , isDirectory = false)          {
+  let result = false;
+  for (const rule of rules) {
+    if (rule.base && !rel.startsWith(`${rule.base}/`)) continue;
+    const local = rule.base ? rel.slice(rule.base.length + 1) : rel;
+    if (rule.directory && !isDirectory && !local.includes('/')) continue;
+    if (rule.regex.test(local)) result = !rule.negate;
+  }
+  return result;
+}
+
+/** Enumerate once. All search, mirror and validation callers receive this same inventory. */
+function admitCodeCorpus(options      = {})      {
+  const { fsImpl = fs, execFileSyncImpl = execFileSync, now = Date.now } = options;
+  const limits = { ...CORPUS_LIMITS, ...options.limits };
+  for (const [name, value] of Object.entries(limits)) if (!Number.isSafeInteger(value) || Number(value) < 1) throw new Error(`invalid corpus limit ${name}`);
+  const root = fsImpl.realpathSync(path.resolve(options.root || process.cwd()));
+  const scopes = Array.isArray(options.scopes) ? options.scopes : [];
+  const inScope = scopeMatcher(scopes);
+  const verifiedDirs = options.verifyDirsOnce ? new Set        () : null;
+  const started = now();
+  const deadline = options.deadline ?? started + limits.timeoutMs;
+  const skipped        = [];
+  const files        = [];
+  const ignoreSources        = [];
+  const ruleCache = new Map               ();
+  let complete = true;
+  let sourceBytes = 0;
+  let readBytes = 0;
+  const reject = (p        , reason        ) => { skipped.push({ path: p, reason }); complete = false; };
+  const rulesFor = (dir        )        => {
+    if (ruleCache.has(dir)) return ruleCache.get(dir) || [];
+    const parent = dir ? path.posix.dirname(dir) : null;
+    const rules = parent !== null ? [...rulesFor(parent === '.' ? '' : parent)] : [];
+    for (const name of ['.gitignore', '.sembleignore']) {
+      const rel = dir ? `${dir}/${name}` : name;
+      const p = path.resolve(root, rel);
+      try {
+        const stat = fsImpl.lstatSync(p);
+        if (!stat.isFile() || stat.size > 65536) { reject(rel, 'invalid-ignore-file'); continue; }
+        const read = readCorpusFile(root, { path: rel }, { maxBytes: 65536, fsImpl, now, deadline });
+        readBytes += read.bytesRead;
+        if (!read.ok) { reject(rel, read.reason); continue; }
+        const text = read.content.toString('utf8');
+        ignoreSources.push([rel, digest(text)]);
+        rules.push(...parseIgnore(text, dir).map((r     ) => ({ ...r, kind: name })));
+      } catch (error     ) { if (error.code !== 'ENOENT') reject(rel, 'ignore-unreadable'); }
+    }
+    ruleCache.set(dir, rules);
+    return rules;
+  };
+  let paths           = [];
+  let gitInventory = false;
+  if (Array.isArray(options.files)) {
+    paths = options.files.map((f     ) => typeof f === 'string' ? f : f.path);
+  } else {
+    try {
+      const data = execFileSyncImpl('git', ['-C', root, 'ls-files', '--cached', '--others', '--exclude-standard', '-z'], {
+        encoding: 'utf8', timeout: Math.max(1, deadline - now()), maxBuffer: limits.maxOutputBytes, stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      if (Buffer.byteLength(String(data), 'utf8') > limits.maxOutputBytes) throw Object.assign(new Error('output limit'), { code: 'ENOBUFS' });
+      paths = String(data).split('\0').filter(Boolean);
+      gitInventory = true;
+    } catch (error     ) {
+      if (error.code === 'ENOBUFS' || error.code === 'ETIMEDOUT' || error.signal) reject('', error.code === 'ENOBUFS' ? 'enumeration-output-limit' : 'deadline');
+      else {
+        const walk = (dir        ) => {
+          if (now() > deadline) { reject(dir, 'deadline'); return; }
+          let entries       ;
+          try { entries = fsImpl.readdirSync(path.join(root, dir), { withFileTypes: true }).sort((a     , b     ) => compareText(a.name, b.name)); }
+          catch { reject(dir, 'directory-unreadable'); return; }
+          const rules = rulesFor(dir);
+          for (const entry of entries) {
+            if (now() > deadline) { reject(dir, 'deadline'); break; }
+            if (EXCLUDED.has(entry.name)) continue;
+            const rel = dir ? `${dir}/${entry.name}` : entry.name;
+            if (ignored(rel, rules, entry.isDirectory())) continue;
+            if (entry.isDirectory()) walk(rel);
+            else paths.push(rel);
+            if (paths.length > limits.maxFiles) { reject(rel, 'file-count-limit'); return; }
+          }
+        };
+        walk('');
+      }
+    }
+  }
+  const unique = [...new Set(paths)].sort(compareText);
+  for (const raw of unique) {
+    if (now() > deadline) { reject('', 'deadline'); break; }
+    const rel = relativeCodePath(raw);
+    if (!rel) { reject(String(raw), 'invalid-path'); continue; }
+    if (rel.split('/').some((p        ) => EXCLUDED.has(p)) || !inScope(rel)) continue;
+    const dir = path.posix.dirname(rel);
+    const rules = rulesFor(dir === '.' ? '' : dir);
+    // Git itself owns gitignore semantics for its inventory; sembleignore always applies.
+    const activeRules = gitInventory ? rules.filter((r     ) => r.kind === '.sembleignore') : rules;
+    if (ignored(rel, activeRules)) continue;
+    const absolutePath = path.resolve(root, rel);
+    try {
+      // `verifiedDirs` (exact requests): containment under the real root is proven per component, each directory once.
+      const stat = verifiedDirs ? statComponents(root, rel.split('/'), { fsImpl, now: () => 0, deadline: Infinity, verifiedDirs }) : fsImpl.lstatSync(absolutePath);
+      if (stat === 'symlink' || !stat.isFile() || stat.isSymbolicLink() || (!verifiedDirs && fsImpl.realpathSync(absolutePath) !== absolutePath)) { reject(rel, 'not-regular-file'); continue; }
+      if (files.length >= limits.maxFiles) { reject(rel, 'file-count-limit'); break; }
+      if (stat.size > limits.maxFileBytes) { reject(rel, 'file-byte-limit'); continue; }
+      if (sourceBytes + stat.size > limits.maxBytes) { reject(rel, 'corpus-byte-limit'); continue; }
+      let fileHash                = null;
+      if (options.hashFiles !== false) {
+        const read = readCorpusFile(root, { path: rel }, { maxBytes: limits.maxFileBytes, fsImpl, now, deadline });
+        readBytes += read.bytesRead;
+        if (!read.ok) { reject(rel, read.reason); continue; }
+        fileHash = read.fileHash;
+      }
+      files.push({ path: rel, absolutePath, sizeBytes: stat.size, fileHash });
+      sourceBytes += stat.size;
+    } catch { reject(rel, 'source-unreadable'); }
+  }
+  const scopeIgnoreDigest = digest(JSON.stringify({ scopes, ignores: ignoreSources.sort((a     , b     ) => compareText(a[0], b[0])), exclusions: [...EXCLUDED].sort() }));
+  const identity = digest(JSON.stringify({ root, scopeIgnoreDigest, files: files.map((f     ) => [f.path, f.sizeBytes, f.fileHash]), complete }));
+  return { schemaVersion: 1, root, identity, scopeIgnoreDigest, files, complete, skipped,
+    coverage: { complete, admittedFiles: files.length, skippedFiles: skipped.length, sourceBytes },
+    accounting: { sourceBytes, readBytes, elapsedMs: Math.max(0, now() - started) },
+    options: { root, files: options.files, scopes, hashFiles: options.hashFiles, limits } };
+}
+
+function fingerprintCorpus(inventory     , options      = {})      {
+  return admitCodeCorpus({ ...inventory.options, root: inventory.root, ...options, hashFiles: true });
+}
+
+module.exports = { CORPUS_LIMITS, compareText, digest, statComponents, relativeCodePath, insideRoot, readCorpusFile, admitCodeCorpus, fingerprintCorpus };

package/src/runtime/knowledge/code-lexical.js

@@ -0,0 +1,130 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readCorpusFile, compareText, digest, CORPUS_LIMITS } = require('./code-corpus.js');
+const STOPWORDS = new Set(['the', 'a', 'an', 'and', 'or', 'but', 'of', 'to', 'in', 'on', 'for', 'with', 'as', 'by', 'at', 'from', 'is', 'are', 'was', 'were', 'be', 'been', 'it', 'its', 'this', 'that', 'these', 'those', 'do', 'does', 'did', 'how', 'what', 'when', 'which', 'who', 'why', 'not', 'no', 'yes', 'can']);
+
+function classifyCodeQuery(query     , { intent }      = {})      {
+  if (typeof query !== 'string' || !query.trim() || Buffer.byteLength(query, 'utf8') > 4096) throw new Error('code query must contain 1..4096 UTF-8 bytes');
+  const text = query.trim();
+  let classificationBasis = 'rule-defaulted';
+  let queryClass = 'conceptual';
+  let literal = text;
+  if (['exact', 'exact-lookup', 'code.exact-search', 'locate-known-symbol'].includes(intent)) { queryClass = 'exact'; classificationBasis = 'declared-exact'; }
+  else if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(text)) { queryClass = 'exact'; classificationBasis = 'identifier'; }
+  else if (/^(?:\.?\.?\/)?[A-Za-z0-9_.@-]+(?:\/[A-Za-z0-9_.@-]+)+$/.test(text) && !text.split('/').includes('..')) { queryClass = 'exact'; classificationBasis = 'relative-path'; }
+  else if (/^[A-Za-z0-9_@-]+\.[A-Za-z0-9_.-]+$/.test(text)) { queryClass = 'exact'; classificationBasis = 'relative-path'; }
+  else if (['"', "'", String.fromCharCode(96)].some((quote        ) => text.startsWith(quote) && text.endsWith(quote))) {
+    literal = text.slice(1, -1);
+    if (!literal) throw new Error('quoted code query cannot be empty');
+    queryClass = 'exact'; classificationBasis = 'quoted-literal';
+  } else if (/\S+\s+\S+/.test(text)) classificationBasis = 'description';
+  return { query: text, queryClass, classificationBasis, literal: queryClass === 'exact' ? literal : null };
+}
+
+function codeTerms(query        )           {
+  return [...new Set(query.toLowerCase().split(/[^a-z0-9]+/).filter((word        ) => word.length >= 2 && !STOPWORDS.has(word)))];
+}
+
+/** Native bounded equivalent of B's per-term content/name ranking over admitted files only. */
+function searchCodeLexical({ inventory, query, classification, intent, maxCandidates = 200, maxOutputBytes = 2 * 1024 * 1024, now = Date.now, timeoutMs = 2000, fsImpl, queryRef = null, retrievalAttemptRef = null }     )      {
+  const routed = classification || classifyCodeQuery(query, { intent });
+  const started = now();
+  const deadline = started + timeoutMs;
+  const terms = routed.queryClass === 'exact' ? [] : codeTerms(routed.query);
+  const rows        = [];
+  const rejected        = [];
+  const filesPerTerm = new Map                ();
+  let complete = true;
+  let readBytes = 0;
+  let searchedFiles = 0;
+  // A binary-looking admitted file, like a file admission skipped (size or count cap, unstaged delete or rename;
+  // X3), is a coverage gap counted with its cause, not a provider fault: `complete` stays the provider outcome
+  // while `coverage.complete` reports every unsearched or unadmitted file.
+  const unsearched        = [];
+  const failures = (p        , reason        ) => { complete = false; rejected.push({ path: p, reason }); };
+  if (!Number.isInteger(maxCandidates) || maxCandidates < 1 || maxCandidates > 200 || !Number.isInteger(maxOutputBytes) || maxOutputBytes < 1) throw new Error('invalid lexical output limits');
+  const exact = routed.queryClass === 'exact';
+  const literal = exact ? routed.literal ?? routed.query : '';
+  // The literal's UTF-8 bytes, searched in the raw buffer (a replacement char could come from invalid bytes, so not then).
+  const literalBytes = exact && !literal.includes('\uFFFD') ? Buffer.from(literal, 'utf8') : null;
+  // Exact search makes one pass over a root proven real once: each directory is proven once per pass, and
+  // only reported files are hashed; live validation re-reads and re-hashes every delivered one (IC-007).
+  let verifiedDirs                     = null;
+  if (exact) { try { if ((fsImpl || fs).realpathSync(inventory.root) === inventory.root) verifiedDirs = new Set        (); } catch { /* full per-file checks */ } }
+  for (const entry of inventory.files) {
+    if (now() > deadline) { failures(entry.path, 'deadline'); break; }
+    const read = readCorpusFile(inventory.root, entry, { fsImpl, maxBytes: CORPUS_LIMITS.maxFileBytes, now, deadline, hash: !exact, verifiedDirs });
+    readBytes += read.bytesRead;
+    if (!read.ok) { failures(entry.path, read.reason); continue; }
+    if (read.content.includes(0)) { unsearched.push({ path: entry.path, reason: 'binary-source' }); continue; }
+    searchedFiles += 1;
+    if (exact) {
+      const named = entry.path === literal || entry.path.split('/').pop() === literal;
+      // A file whose bytes lack the literal has no matching line; skip decoding and splitting it.
+      if (literalBytes && !named && !read.content.includes(literalBytes)) continue;
+      const lines = read.content.toString('utf8').split('\n');
+      const fileHash = read.fileHash || digest(read.content);
+      let contentHit = false;
+      for (let index = 0; index < lines.length; index += 1) {
+        if (now() > deadline) { failures(entry.path, 'deadline'); break; }
+        if (!lines[index].includes(literal)) continue;
+        rows.push({ path: entry.path, line: index + 1, fileHash });
+        contentHit = true;
+        if (rows.length > maxCandidates) break;
+      }
+      if (!contentHit && named) rows.push({ path: entry.path, line: 1, fileHash });
+      if (rows.length > maxCandidates) { failures(entry.path, 'candidate-limit'); break; }
+    } else {
+      const text = read.content.toString('utf8');
+      const hits = new Map             ();
+      let total = 0;
+      const lower = text.split('\n').map((line        ) => line.toLowerCase());
+      for (const term of terms) {
+        for (let index = 0; index < lower.length; index += 1) {
+          if (now() > deadline) { failures(entry.path, 'deadline'); break; }
+          if (!lower[index].includes(term)) continue;
+          total += 1;
+          if (!hits.has(term)) hits.set(term, { first: index + 1 });
+        }
+        if (hits.has(term)) filesPerTerm.set(term, (filesPerTerm.get(term) || 0) + 1);
+      }
+      const name = terms.filter((term        ) => entry.path.split('/').pop().toLowerCase().includes(term)).length;
+      if (hits.size || name) rows.push({ path: entry.path, hits, name, total, score: hits.size + name, fileHash: read.fileHash });
+    }
+  }
+  // After the pass, re-prove every directory it trusted; rows read under one that changed are dropped.
+  if (verifiedDirs) {
+    const changed           = [];
+    for (const dir of verifiedDirs) { try { if ((fsImpl || fs).lstatSync(dir).isSymbolicLink()) changed.push(dir); } catch { changed.push(dir); } }
+    if (changed.length) {
+      const moved = new Set        ();
+      for (const row of rows) if (changed.some((dir) => path.join(inventory.root, row.path).startsWith(dir + path.sep))) moved.add(row.path);
+      for (const p of moved) failures(p, 'source-changed');
+      for (let i = rows.length - 1; i >= 0; i -= 1) if (moved.has(rows[i].path)) rows.splice(i, 1);
+    }
+  }
+  if (routed.queryClass === 'exact') rows.sort((a     , b     ) => compareText(a.path, b.path) || a.line - b.line);
+  else rows.sort((a     , b     ) => b.score - a.score || b.total - a.total || compareText(a.path, b.path));
+  if (rows.length > maxCandidates) failures('', 'candidate-limit');
+  const candidates        = [];
+  let outputBytes = 2;
+  for (const row of rows.slice(0, maxCandidates)) {
+    const term = row.hits ? [...row.hits.keys()].sort((a        , b        ) => (filesPerTerm.get(a) || 0) - (filesPerTerm.get(b) || 0) || compareText(a, b))[0] : null;
+    const line = row.line ?? (term ? row.hits.get(term).first : 1);
+    const candidate = { locator: { file: row.path, line, endLine: line }, provider: 'native.rg', capability: routed.queryClass === 'exact' ? 'code.exact-search' : 'code.semantic-search',
+      queryRef, retrievalAttemptRef, sourceVersion: { gitCommit: null, fileHash: row.fileHash, isDirty: null }, rank: candidates.length + 1 };
+    const size = Buffer.byteLength(JSON.stringify(candidate), 'utf8') + 1;
+    if (outputBytes + size > maxOutputBytes) { failures(row.path, 'output-byte-limit'); break; }
+    outputBytes += size;
+    candidates.push(candidate);
+  }
+  const skipped = [...rejected, ...unsearched];
+  return { candidates, queryClass: routed.queryClass, classificationBasis: routed.classificationBasis,
+    complete, coverage: { complete: complete && unsearched.length === 0 && Boolean(inventory.complete), searchedFiles, skipped, skippedFiles: skipped.length,
+      skippedByReason: skipped.reduce((counts     , s     ) => ({ ...counts, [s.reason]: (counts[s.reason] || 0) + 1 }), {}) },
+    accounting: { readBytes, outputBytes, rawCandidates: rows.length, elapsedMs: Math.max(0, now() - started) }, rejections: rejected };
+}
+
+module.exports = { classifyCodeQuery, codeTerms, searchCodeLexical };