@khoavu882/doflow 2.0.0-beta.5 → 2.0.0

package/src/runtime/knowledge/hybrid.js

@@ -11,7 +11,7 @@ const path = require('node:path');
  * @param {{ k?: number }} [options]
  * @returns {Array<{ id: string, rrfScore: number }>}
  */
-function reciprocalRankFusion(rankedLists         , { k = 60 }                 = {})        {
+function reciprocalRankFusion(rankedLists         , { k = 60, fullPrecision = false }                                          = {})        {
   const scores = new Map                ();
   const items = new Map             ();
 
@@ -26,9 +26,7 @@ function reciprocalRankFusion(rankedLists         , { k = 60 }                 =
       if (!id) continue;
       const rrf = 1 / (k + rank + 1);
       scores.set(id, (scores.get(id) || 0) + rrf);
-      if (!items.has(id)) {
-        items.set(id, item);
-      }
+      if (!items.has(id)) items.set(id, item);
     }
   }
 
@@ -37,7 +35,7 @@ function reciprocalRankFusion(rankedLists         , { k = 60 }                 =
     fused.push({
       ...items.get(id),
       id,
-      rrfScore: Number(rrfScore.toFixed(6)),
+      rrfScore: fullPrecision ? rrfScore : Number(rrfScore.toFixed(6)),
     });
   }
 
@@ -51,21 +49,22 @@ function reciprocalRankFusion(rankedLists         , { k = 60 }                 =
  * @param {string} [projectRoot]
  * @returns {{ file: string, line?: number, endLine?: number }}
  */
+const slashed = (p        )         => p.split(path.sep).join('/');
 function normalizeLocator(raw     , projectRoot         = process.cwd())                                                    {
   if (!raw) return { file: '' };
   if (typeof raw === 'string') {
     const match = raw.match(/^([^:]+)(?::(\d+))?(?::(\d+))?$/);
     if (match) {
-      const relFile = path.isAbsolute(match[1]) ? path.relative(projectRoot, match[1]) : match[1];
+      const relFile = slashed(path.isAbsolute(match[1]) ? path.relative(projectRoot, match[1]) : match[1]);
       return {
         file: relFile,
         ...(match[2] ? { line: parseInt(match[2], 10) } : {}),
       };
     }
-    return { file: path.isAbsolute(raw) ? path.relative(projectRoot, raw) : raw };
+    return { file: slashed(path.isAbsolute(raw) ? path.relative(projectRoot, raw) : raw) };
   }
   if (typeof raw === 'object' && raw.file) {
-    const relFile = path.isAbsolute(raw.file) ? path.relative(projectRoot, raw.file) : raw.file;
+    const relFile = slashed(path.isAbsolute(raw.file) ? path.relative(projectRoot, raw.file) : raw.file);
     return {
       file: relFile,
       ...(raw.line ? { line: raw.line } : {}),
@@ -142,8 +141,137 @@ function fuseHybridResults({
   return candidates;
 }
 
+/** Strict code candidates are separate from the legacy guidance locator string convention. */
+function normalizeCodeCandidates(items       , { projectRoot = process.cwd(), provider, capability, corpusIdentity = '', queryRef = null, retrievalAttemptRef = null }      = {})      {
+  const { relativeCodePath } = require('./code-corpus.js');
+  const candidates        = [];
+  const rejected        = [];
+  for (const item of Array.isArray(items) ? items : []) {
+    let raw      = item?.locator || item?.path || item?.file;
+    let loc     ;
+    if (typeof raw === 'string') {
+      const match = /^(.*?):(\d+)(?::(\d+))?$/.exec(raw);
+      if (match) loc = { file: match[1], line: Number(match[2]), endLine: Number(match[3] || match[2]) };
+      else loc = { file: raw, line: item.startLine ?? item.line ?? 1, endLine: item.endLine ?? item.startLine ?? item.line ?? 1 };
+    } else if (raw && typeof raw === 'object') {
+      loc = { file: raw.file, line: raw.line ?? raw.startLine ?? 1, endLine: raw.endLine ?? raw.line ?? raw.startLine ?? 1 };
+    }
+    if (loc && typeof loc.file === 'string' && path.isAbsolute(loc.file)) loc.file = path.relative(projectRoot, loc.file);
+    const file = relativeCodePath(loc?.file);
+    if (!file || !Number.isInteger(loc.line) || !Number.isInteger(loc.endLine) || loc.line < 1 || loc.endLine < loc.line) {
+      rejected.push({ locator: raw ?? null, reason: 'invalid-locator' }); continue;
+    }
+    loc.file = file;
+    const id = JSON.stringify([corpusIdentity, file, loc.line, loc.endLine]);
+    const actualProvider = item.provider || provider;
+    const actualCapability = item.capability || capability;
+    const origin = { provider: actualProvider, capability: actualCapability, queryRef: item.queryRef ?? queryRef,
+      retrievalAttemptRef: item.retrievalAttemptRef ?? retrievalAttemptRef,
+      originalRank: candidates.length + 1, sourceVersion: item.sourceVersion ?? null };
+    const origins = item.origins?.length ? item.origins.map((o     ) => ({ ...origin, ...o })) : [origin];
+    candidates.push({ ...item, schemaVersion: 1, id, locator: loc, provider: actualProvider, capability: actualCapability, origins });
+  }
+  return { candidates, rejected };
+}
+
+function addOrigins(bucket       , origins       ) {
+  for (const origin of origins) {
+    const serialized = JSON.stringify(origin);
+    if (!bucket.some((o     ) => JSON.stringify(o) === serialized)) bucket.push(origin);
+  }
+}
+
+/** RRF terms summed in ascending-rank order, so equal rank multisets give bit-identical scores (DEC-016). */
+function rrfSum(ranks          , k        )         {
+  return [...ranks].sort((a, b) => a - b).reduce((sum, rank) => sum + 1 / (k + rank), 0);
+}
+
+/**
+ * File-grain fusion for conceptual requests with more than one voting provider (IC-006, DEC-025). A provider's
+ * rank for a file is its dense rank over distinct files; it votes only within its first `depth` files. Voted
+ * files order by capped RRF, then full-depth RRF, then path; files outside every provider's depth form an
+ * unscored tail ordered by smallest provider rank, then path. The delivered locator is the widest of each
+ * provider's first-ranked span on the file (ties: better provider rank, smaller line, endLine, provider id),
+ * always a span some provider returned.
+ */
+function fuseByFile(providerLists                    , { corpusIdentity, k, depth, compareText }     )        {
+  const files = new Map                                          ();
+  for (const [provider, list] of providerLists) {
+    let rank = 0;
+    for (const item of list) {
+      const file = item.locator.file;
+      if (!files.has(file)) files.set(file, { votes: [], origins: [] });
+      const entry = files.get(file) ;
+      if (!entry.votes.some((vote     ) => vote.provider === provider)) { rank += 1; entry.votes.push({ provider, rank, item }); }
+      const locator = { file, line: item.locator.line, endLine: item.locator.endLine };
+      addOrigins(entry.origins, item.origins.map((origin     ) => ({ ...origin, locator })));
+    }
+  }
+  const width = (vote     ) => vote.item.locator.endLine - vote.item.locator.line;
+  const fused = [...files.entries()].map(([file, { votes, origins }]) => {
+    const ranks = votes.map((vote     ) => vote.rank);
+    const [delivered] = [...votes].sort((a     , b     ) => width(b) - width(a) || a.rank - b.rank
+      || a.item.locator.line - b.item.locator.line || a.item.locator.endLine - b.item.locator.endLine || compareText(a.provider, b.provider));
+    return { candidate: { ...delivered.item, id: JSON.stringify([corpusIdentity, file]), locator: { ...delivered.item.locator }, origins,
+      rrfScore: rrfSum(ranks.filter((rank        ) => rank <= depth), k) },
+    file, full: rrfSum(ranks, k), best: Math.min(...ranks) };
+  });
+  fused.sort((a     , b     ) => {
+    const voted = Number(b.candidate.rrfScore > 0) - Number(a.candidate.rrfScore > 0);
+    if (voted) return voted;
+    if (a.candidate.rrfScore > 0) return b.candidate.rrfScore - a.candidate.rrfScore || b.full - a.full || compareText(a.file, b.file);
+    return a.best - b.best || compareText(a.file, b.file);
+  });
+  return fused.map((entry     ) => entry.candidate);
+}
+
+/**
+ * One vote per provider and identity, all origins retained, full precision until presentation. Span grain
+ * (exact requests, single-provider lists) keeps `(corpus identity, file, line, endLine)`; `grain: 'file'`
+ * with two or more voting providers fuses by file with vote depth `depth` (IC-006, DEC-025).
+ */
+function fuseRankedCandidates({ rankedLists, projectRoot = process.cwd(), corpusIdentity = '', k = 60, grain = 'span', depth = Infinity }     )      {
+  const { compareText } = require('./code-corpus.js');
+  const providerLists = new Map               ();
+  const items        = [];
+  const rejected        = [];
+  for (let listIndex = 0; listIndex < rankedLists.length; listIndex += 1) {
+    const list = rankedLists[listIndex];
+    const normalized = normalizeCodeCandidates(Array.isArray(list) ? list : list.candidates,
+      { projectRoot, corpusIdentity, provider: list.provider || 'list-' + listIndex, capability: list.capability,
+        queryRef: list.queryRef, retrievalAttemptRef: list.retrievalAttemptRef });
+    rejected.push(...normalized.rejected);
+    for (const item of normalized.candidates) {
+      if (!providerLists.has(item.provider)) providerLists.set(item.provider, []);
+      providerLists.get(item.provider) .push(item);
+      items.push(item);
+    }
+  }
+  if (grain === 'file' && providerLists.size > 1) {
+    const candidates = fuseByFile(providerLists, { corpusIdentity, k, depth, compareText });
+    candidates.forEach((candidate     , index        ) => { candidate.rank = index + 1; });
+    return { candidates, rejected };
+  }
+  const origins = new Map               ();
+  for (const item of items) {
+    if (!origins.has(item.id)) origins.set(item.id, []);
+    addOrigins(origins.get(item.id) , item.origins);
+  }
+  const uniqueProviderLists = [...providerLists.values()].map((list       ) => {
+    const seen = new Set        ();
+    return list.filter((item     ) => { if (seen.has(item.id)) return false; seen.add(item.id); return true; });
+  });
+  const candidates = reciprocalRankFusion(uniqueProviderLists, { k, fullPrecision: true }).map((item     ) => ({ ...item, origins: origins.get(item.id) }));
+  candidates.sort((a     , b     ) => b.rrfScore - a.rrfScore || compareText(a.locator.file, b.locator.file)
+    || a.locator.line - b.locator.line || a.locator.endLine - b.locator.endLine);
+  candidates.forEach((candidate     , index        ) => { candidate.rank = index + 1; });
+  return { candidates, rejected };
+}
+
 module.exports = {
   reciprocalRankFusion,
   normalizeLocator,
+  normalizeCodeCandidates,
+  fuseRankedCandidates,
   fuseHybridResults,
 };

package/src/runtime/knowledge/retrieval.js

@@ -145,7 +145,15 @@ function searchGuidance({ corpusDir, indexDir, query, k = 5, fsImpl = fs }
  * code from this install, knowledge from the project being worked on. The `.doflow` root is
  * $DOFLOW_CONFIG_DIR, else the nearest one above `stateRoot` that holds a guidance tree, else the
  * home install; the index is kept beside the corpus chosen. */
-function handleRetrieveCommand({ query, top, json = false, stateRoot }                                                              = {})      {
+function handleRetrieveCommand(options      = {})      {
+  const { query, top, json = false, stateRoot } = options;
+  if (options.scope !== undefined && options.scope !== 'guidance' && options.scope !== 'code') {
+    return usageError('retrieve', `--scope must be guidance or code, got '${options.scope}'`, json);
+  }
+  if (options.scope === 'code' || options.indexAction !== undefined) {
+    if (options.scope !== 'code') return usageError('retrieve', '--index-action requires --scope code', json);
+    return handleCodeRetrieveCommand(options);
+  }
   const { configDir } = resolveRunsLocation({ start: stateRoot, containing: 'guidance' });
   const corpusDir = path.join(configDir, 'guidance');
   const indexDir = path.join(configDir, 'index', 'guidance');
@@ -174,6 +182,30 @@ function handleRetrieveCommand({ query, top, json = false, stateRoot }
   }
 }
 
+/** Additive code path. The guidance branch above retains its existing output and exit behavior. The search root is
+ * `root` or cwd, never `stateRoot`: in a linked worktree the state root is the main checkout's feature store. */
+function handleCodeRetrieveCommand(options     )      {
+  const { executeCodeRetrieval } = require('./code-retrieval.js');
+  return executeCodeRetrieval({ ...options, root: options.root || process.cwd() }).then((outcome     ) => {
+    const response = outcome.response;
+    if (options.json) console.log(JSON.stringify(response, null, 2));
+    else if (!response.ok) console.error(`[ERROR] retrieve: ${response.error}${response.cause ? ` (${response.cause})` : ''}${response.summary ? ` — ${response.summary}` : ''}`);
+    else if (response.action) console.log(`${response.complete ? '[OK]' : '[ERROR]'} ${response.action} code index${response.generation ? ` ${response.generation}` : ''}`);
+    else if (!response.results.length) console.log('[OK] No matching code found in the attempted scope. absenceEstablished=false');
+    else response.results.forEach((candidate     , index        ) => {
+      console.log(`${index + 1}. ${candidate.locator.file}:${candidate.locator.line}-${candidate.locator.endLine}`);
+      if (candidate.snippet) console.log(`   ${candidate.snippet}`);
+    });
+    if (!options.json && response.gaps?.length) for (const gap of response.gaps) console.error(`[INFO] retrieve gap: ${gap.provider || gap.source || 'retrieval'} ${gap.reason}`);
+    return finishRuntime(outcome.exit);
+  }).catch((error     ) => {
+    captureCaught(error, 'retrieve', 1);
+    if (options.json) console.log(JSON.stringify({ ok: false, schemaVersion: 1, scope: 'code', error: 'retrieval-failed', cause: error.message }, null, 2));
+    else console.error(`[ERROR] retrieve: ${error.message}`);
+    return finishRuntime(1);
+  });
+}
+
 const {
   reciprocalRankFusion,
   normalizeLocator,
@@ -187,6 +219,7 @@ module.exports = {
   buildImportGraph,
   expandViaGraph,
   handleRetrieveCommand,
+  handleCodeRetrieveCommand,
   STOPWORDS,
   reciprocalRankFusion,
   normalizeLocator,

package/src/runtime/knowledge/rtk-compress.js

@@ -0,0 +1,77 @@
+'use strict';
+
+                                
+                   
+                          
+                
+                          
+                             
+ 
+
+function formatWithRTK(
+  resolution     ,
+  options                        
+)                       {
+  const rawJson = JSON.stringify(resolution, null, 2);
+  const rawChars = rawJson.length;
+
+  const lines           = [];
+  const statusMark = resolution.status === 'HEALTHY' ? '✓' : resolution.status === 'FALLBACK' ? '▲' : '✗';
+  lines.push(`${statusMark} [${resolution.provider}] query: "${resolution.query}" (status: ${resolution.status}, freshness: ${resolution.freshness})`);
+
+  if (resolution.fallbackReason) {
+    lines.push(`  fallback-reason: ${resolution.fallbackReason}`);
+  }
+
+  if (resolution.isAbsence) {
+    lines.push(`  absence: true (${resolution.absenceReason || 'zero occurrences'})`);
+  }
+
+  const maxLines = options?.maxLines ?? 50;
+  const candidates = Array.isArray(resolution.candidates) ? resolution.candidates : [];
+  const totalCandidates = candidates.length;
+  const displayedCandidates = candidates.slice(0, maxLines);
+
+  for (const cand of displayedCandidates) {
+    const loc = cand.locator || {};
+    const fileLine = loc.line !== undefined ? `${loc.file}:${loc.line}` : loc.file;
+    const relStr = cand.relation ? ` [${cand.relation}]` : '';
+    const symStr = loc.symbol ? ` ${loc.symbol}` : '';
+    const scoreStr = typeof cand.score === 'number' ? ` (${cand.score.toFixed(2)})` : '';
+    lines.push(`  #${cand.rank ?? 0} ${fileLine}${symStr}${relStr}${scoreStr}`);
+  }
+
+  if (totalCandidates > maxLines) {
+    lines.push(`  ... (${totalCandidates - maxLines} more candidates truncated)`);
+  }
+
+  const formattedOutput = lines.join('\n');
+  const compressedChars = formattedOutput.length;
+  const ratio = rawChars > 0 ? Number((compressedChars / rawChars).toFixed(3)) : 1.0;
+
+  let locatorsPreserved = true;
+  for (const cand of displayedCandidates) {
+    const loc = cand.locator;
+    if (!loc || !loc.file) continue;
+    if (!formattedOutput.includes(loc.file)) {
+      locatorsPreserved = false;
+      break;
+    }
+    if (loc.line !== undefined && !formattedOutput.includes(`${loc.file}:${loc.line}`)) {
+      locatorsPreserved = false;
+      break;
+    }
+  }
+
+  return {
+    rawChars,
+    compressedChars,
+    ratio,
+    formattedOutput,
+    locatorsPreserved,
+  };
+}
+
+module.exports = {
+  formatWithRTK,
+};

package/src/runtime/knowledge/semble-bridge.py

@@ -0,0 +1,106 @@
+"""Semble 0.7.0 public API adapter. One bounded JSON request per process.
+
+The audit policy denies network and child processes even on model loader retry paths.
+It also confines Python writes to the invocation's declared project-local cache/staging.
+No library function or private provider implementation is patched.
+"""
+import importlib.metadata
+import json
+import math
+import os
+import platform
+from pathlib import Path
+import sys
+
+VERSION = "0.7.0"  # must equal SEMBLE_VERSION in semble-provider.ts (tested)
+RUNTIME_PACKAGES = ("numpy", "model2vec", "tokenizers", "huggingface-hub", "safetensors", "vicinity")
+
+
+def runtime_identity():
+    packages = {}
+    for name in RUNTIME_PACKAGES:
+        try:
+            packages[name] = importlib.metadata.version(name)
+        except importlib.metadata.PackageNotFoundError as error:
+            raise RuntimeError("provider-runtime-dependency-missing") from error
+    return {"python": platform.python_version(), "implementation": platform.python_implementation(),
+            "platform": platform.platform(), "machine": platform.machine(), "packages": packages}
+
+
+def install_policy(roots):
+    roots = tuple(Path(root).resolve(strict=True) for root in roots)
+
+    def permitted(value):
+        if isinstance(value, int):
+            return True  # already opened standard output/error descriptors
+        candidate = Path(os.fsdecode(value)).resolve()
+        return any(candidate == root or root in candidate.parents for root in roots)
+
+    def audit(event, args):
+        if event.startswith("socket.") or event in ("subprocess.Popen", "os.system", "os.exec", "os.posix_spawn", "os.fork"):
+            raise PermissionError("provider-network-or-subprocess-denied")
+        if event == "open":
+            file, mode, flags = args
+            writing = (isinstance(mode, str) and any(c in mode for c in "wax+")) or bool(flags & (os.O_WRONLY | os.O_RDWR | os.O_CREAT | os.O_TRUNC | os.O_APPEND))
+            if writing and not permitted(file):
+                raise PermissionError("provider-write-outside-state")
+        if event in ("os.mkdir", "os.remove", "os.rmdir", "os.chmod", "os.utime", "os.truncate") and not permitted(args[0]):
+            raise PermissionError("provider-write-outside-state")
+        if event in ("os.rename", "os.link", "os.symlink"):
+            if not permitted(args[0]) or not permitted(args[1]) or event != "os.rename":
+                raise PermissionError("provider-unsafe-mutation")
+    sys.addaudithook(audit)
+
+
+def run(request):
+    install_policy(request["allowedWriteRoots"])
+    try:
+        found = importlib.metadata.version("semble")
+    except importlib.metadata.PackageNotFoundError:
+        return {"ok": False, "reason": "provider-unavailable", "cause": f"semble is not installed for {sys.executable}"}
+    if found != VERSION:
+        return {"ok": False, "reason": "provider-version-mismatch", "cause": f"{sys.executable} has semble {found[:32]}; the bridge pins {VERSION}"}
+    from semble.index import SembleIndex
+    from semble.types import ContentType
+    if request["action"] == "query":
+        index = SembleIndex.load_from_disk(Path(request["indexPath"]))
+        count = request["poolSize"]
+        if index.stats.total_chunks != count:
+            raise ValueError("persisted chunk count changed")
+        results = index.search(request["query"], top_k=200, alpha=1.0, rerank=False)
+        candidates = []
+        for result in results:
+            chunk = result.chunk
+            score = float(result.score)
+            if not math.isfinite(score):
+                raise ValueError("nonfinite score")
+            candidates.append({"locator": {"file": chunk.file_path, "line": chunk.start_line, "endLine": chunk.end_line}, "score": score})
+        # Public scores are provider-native distinct ranks; sorting them cannot
+        # recover dense ties hidden inside Semble. Preserve the returned order.
+        return {"ok": True, "candidates": candidates, "poolSize": count}
+    if request["action"] not in ("build", "refresh"):
+        raise ValueError("invalid action")
+    index = SembleIndex.from_path(Path(request["mirror"]), model_path=request["modelPath"], content=(ContentType.CODE,), show_progress_bar=False)
+    index.save(Path(request["savePath"]))
+    return {"ok": True}
+
+
+def main():
+    try:
+        request = json.loads(sys.stdin.buffer.read(2097153))
+        result = run(request)
+    except importlib.metadata.PackageNotFoundError:
+        result = {"ok": False, "reason": "provider-unavailable"}
+    except (ImportError, AttributeError):
+        result = {"ok": False, "reason": "provider-api-unavailable"}
+    except Exception:
+        # Provider exception text may contain source/query data. Return only a fixed cause.
+        result = {"ok": False, "reason": "provider-load-or-operation-error"}
+    if result.get("ok"):
+        result["runtimeIdentity"] = runtime_identity()
+    result["version"] = VERSION
+    print(json.dumps(result, separators=(",", ":")))
+
+
+if __name__ == "__main__":
+    main()

package/src/runtime/knowledge/semble-lifecycle.js

@@ -0,0 +1,114 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { SEMBLE_VERSION, SEMBLE_LIMITS, semanticStatePaths, fault, digest, safeDirectories, regularBytes,
+  inspectModel, validateInventory, readSource, checkSources, inspectArtifacts, acquireSemanticLock,
+  cleanupTemporary, executeBridge, readCompleted, scanTree, resolveSembleInterpreter, checkSembleVersion } = require('./semble-provider.js');
+
+/**
+ * The in-progress marker never follows a link out of the state directory. A failed mutation leaves a regular
+ * marker behind on purpose, so a regular file is replaced; anything else (a symlink, a directory) is refused.
+ * The create is `wx` (O_CREAT|O_EXCL), which fails on any existing path, a symlink included, so a link planted
+ * between the unlink and the create is refused too rather than written through.
+ */
+function writeMarker(marker        , body        )       {
+  let found      = null;
+  try { found = fs.lstatSync(marker); } catch (error     ) { if (error.code !== 'ENOENT') throw error; }
+  if (found && !found.isFile()) throw fault('unsafe-state-file');
+  if (found) fs.unlinkSync(marker);
+  try { fs.writeFileSync(marker, body, { flag: 'wx', mode: 0o600 }); }
+  catch (error     ) { if (error.code === 'EEXIST') throw fault('unsafe-state-file'); throw error; }
+}
+
+/** Explicit operations only. A failed mutation deliberately keeps its in-progress marker. */
+async function runSembleLifecycle(options     )               {
+  const started = Date.now(); const limits = { ...SEMBLE_LIMITS, ...options.limits };
+  const { inventory, action } = options; let release     ; let staging                    ;
+  let added = 0; let changed = 0; let deleted = 0; let changedBytes = 0;
+  const checkDeadline = () => { if (Date.now() - started > limits.lifecycleMs) throw fault('lifecycle-timeout'); };
+  try {
+    if (action !== 'build' && action !== 'refresh') throw fault('invalid-index-action');
+    validateInventory(inventory, limits); const model = inspectModel(options.modelPath, limits);
+    const python = options.python || resolveSembleInterpreter().python; checkSembleVersion(python); // preflight: before any lock or mutation
+    const paths = semanticStatePaths(inventory); release = await acquireSemanticLock(paths); cleanupTemporary(paths);
+    let previous      = null;
+    if (action === 'refresh') {
+      previous = readCompleted(paths, inventory, model, limits, true);
+      const oldInventory = { ...inventory, files: previous.files };
+      const artifacts = inspectArtifacts(paths.index, oldInventory, paths, model, limits);
+      if (artifacts.artifactIdentity !== previous.artifactIdentity) throw fault('incompatible-refresh-index');
+    }
+    const old = new Map((previous?.files || []).map((entry     ) => [entry.path, entry]));
+    const current = new Set(inventory.files.map((entry     ) => entry.path));
+    for (const entry of inventory.files) {
+      const prior      = old.get(entry.path);
+      if (!prior) { added++; changedBytes += entry.sizeBytes; }
+      else if (prior.fileHash !== entry.fileHash) { changed++; changedBytes += entry.sizeBytes; }
+    }
+    deleted = [...old.keys()].filter((file     ) => !current.has(file)).length;
+    if (action === 'refresh' && (added + changed + deleted > limits.changedFiles || changedBytes > limits.changedBytes)) throw fault('refresh-limit');
+    checkSources(inventory, limits); checkDeadline();
+    staging = fs.mkdtempSync(path.join(paths.state, 'staging-'));
+    const sourceStage = path.join(staging, 'source'); fs.mkdirSync(sourceStage);
+    // Stage verified ordinary copies before invalidating or modifying the stable mirror.
+    for (const entry of inventory.files) {
+      checkDeadline();
+      if (old.has(entry.path) && (old.get(entry.path)       ).fileHash === entry.fileHash) continue;
+      const dest = path.join(sourceStage, entry.path); safeDirectories(sourceStage, path.dirname(dest), true);
+      fs.writeFileSync(dest, readSource(inventory, entry, limits), { flag: 'wx' });
+    }
+    checkSources(inventory, limits); checkDeadline();
+    writeMarker(paths.marker, JSON.stringify({ schemaVersion: 1, action, startedAt: new Date().toISOString() }));
+    if (action === 'build') {
+      // A repair build explicitly discards incompatible cache; never let from_path silently reuse it.
+      for (const dir of [paths.mirror, paths.cache]) if (fs.existsSync(dir)) { scanTree(dir, limits.artifactBytes); fs.rmSync(dir, { recursive: true }); }
+    }
+    safeDirectories(paths.state, paths.mirror, true); safeDirectories(paths.state, paths.cache, true);
+    for (const file of old.keys()       ) if (!current.has(file)) fs.unlinkSync(path.join(paths.mirror, file));
+    for (const entry of inventory.files) {
+      checkDeadline(); const staged = path.join(sourceStage, entry.path);
+      if (!fs.existsSync(staged)) continue;
+      const dest = path.join(paths.mirror, entry.path); safeDirectories(paths.mirror, path.dirname(dest), true);
+      let previousMtime = 0; try { previousMtime = fs.lstatSync(dest).mtimeMs; } catch {}
+      fs.renameSync(staged, dest);
+      // A hash change must be newer than both the prior copy and saved provider time, even on coarse filesystems.
+      const seconds = Math.max(Date.now() / 1000, previousMtime / 1000 + 2, (previous?.providerTime || 0) + 2);
+      fs.utimesSync(dest, seconds, seconds);
+    }
+    const temp = path.join(staging, 'provider'); fs.mkdirSync(temp);
+    const savePath = path.join(staging, 'index');
+    const result = await executeBridge({ action, mirror: paths.mirror, modelPath: model.path, savePath, indexPath: paths.index,
+      allowedWriteRoots: [staging, paths.cache] }, { ...options, python, limits: { ...limits, lifecycleMs: Math.max(1, limits.lifecycleMs - (Date.now() - started)) } }, paths, temp);
+    if (!result.ok) throw fault(result.reason || 'provider-error', 'UNKNOWN', typeof result.cause === 'string' ? result.cause : undefined);
+    if (!result.runtimeIdentity || typeof result.runtimeIdentity !== 'object') throw fault('provider-runtime-identity-unavailable');
+    const artifacts = inspectArtifacts(savePath, inventory, paths, model, limits);
+    checkSources(inventory, limits); checkDeadline();
+    if (inspectModel(options.modelPath, limits).identity !== model.identity) throw fault('model-changed', 'STALE');
+    const generation = crypto.randomUUID();
+    safeDirectories(paths.state, path.dirname(paths.index), true);
+    const backup = path.join(staging, 'previous-index');
+    if (fs.existsSync(paths.index)) fs.renameSync(paths.index, backup);
+    fs.renameSync(savePath, paths.index);
+    const metadata = JSON.parse(regularBytes(path.join(paths.index, 'metadata.json'), limits.artifactBytes).toString('utf8'));
+    const manifest = { schemaVersion: 1, complete: true, providerVersion: SEMBLE_VERSION, runtimeIdentity: result.runtimeIdentity, root: inventory.root,
+      scopeIgnoreDigest: inventory.scopeIgnoreDigest, corpusIdentity: inventory.identity, model, generation,
+      providerTime: metadata.time, artifactIdentity: artifacts.artifactIdentity,
+      files: inventory.files.map((entry     ) => ({ path: entry.path, sizeBytes: entry.sizeBytes, fileHash: entry.fileHash })) };
+    const pending = path.join(staging, 'manifest.json'); fs.writeFileSync(pending, JSON.stringify(manifest));
+    checkSources(inventory, limits); checkDeadline();
+    fs.renameSync(pending, paths.manifest); // Completion metadata is always the last published artifact.
+    fs.unlinkSync(paths.marker);
+    return { ok: true, action, complete: true, freshness: 'FRESH', generation, added, changed, deleted, skipped: 0,
+      bytes: changedBytes, elapsedMs: Date.now() - started, chunks: artifacts.chunks, artifactBytes: artifacts.artifactBytes };
+  } catch (error     ) {
+    const reason = error.reason || 'lifecycle-error';
+    return { ok: false, action, complete: false, freshness: error.freshness || 'UNKNOWN', reason, ...(typeof error.cause === 'string' ? { cause: error.cause } : {}),
+      added, changed, deleted, skipped: inventory?.skipped?.length || 0, bytes: changedBytes, elapsedMs: Date.now() - started,
+      // A build needs the same lock, so contention is never repaired by "run a build".
+      repair: reason === 'lock-contention' ? 'Wait for the other semantic index operation to finish, then run this command again (see cause).'
+        : 'Run an explicit bounded build with a verified local model after correcting the cause.' };
+  } finally { try { if (staging) fs.rmSync(staging, { recursive: true, force: true }); } catch {} try { if (release) release(); } catch {} }
+}
+module.exports = { runSembleLifecycle };