cgraphx 2.0.2 → 2.0.3

package/dist/core/code/engine/core/run-analyze.js

@@ -0,0 +1,1098 @@
+"use strict";
+/**
+ * Shared Analysis Orchestrator
+ *
+ * Extracts the core analysis pipeline from the CLI analyze command into a
+ * reusable function that can be called from both the CLI and a server-side
+ * worker process.
+ *
+ * IMPORTANT: This module must NEVER call process.exit(). The caller (CLI
+ * wrapper or server worker) is responsible for process lifecycle.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveStreamGraphEmit = exports.collectBranchCacheKeys = exports.PHASE_LABELS = void 0;
+exports.runFullAnalysis = runFullAnalysis;
+const path_1 = __importDefault(require("path"));
+const promises_1 = __importDefault(require("fs/promises"));
+const node_crypto_1 = require("node:crypto");
+const node_url_1 = require("node:url");
+const fs_atomic_js_1 = require("../storage/fs-atomic.js");
+const index_lock_js_1 = require("../storage/index-lock.js");
+const pipeline_js_1 = require("./ingestion/pipeline.js");
+const workspace_config_js_1 = require("./ingestion/workspace-config.js");
+const unresolved_receivers_js_1 = require("./ingestion/scope-resolution/unresolved-receivers.js");
+const safe_parse_js_1 = require("./tree-sitter/safe-parse.js");
+const lbug_adapter_js_1 = require("./lbug/lbug-adapter.js");
+const lbug_config_js_1 = require("./lbug/lbug-config.js");
+const wal_checkpoint_driver_js_1 = require("./lbug/wal-checkpoint-driver.js");
+const sidecar_recovery_js_1 = require("./lbug/sidecar-recovery.js");
+const repo_manager_js_1 = require("../storage/repo-manager.js");
+const env_js_1 = require("./ingestion/utils/env.js");
+const file_hash_js_1 = require("../storage/file-hash.js");
+const parse_cache_js_1 = require("../storage/parse-cache.js");
+const parsedfile_store_js_1 = require("../storage/parsedfile-store.js");
+const git_js_1 = require("../storage/git.js");
+const analyze_config_js_1 = require("../cli/analyze-config.js");
+const schema_js_1 = require("./lbug/schema.js");
+const bean_factories_js_1 = require("./ingestion/frameworks/spring/bean-factories.js");
+const analysis_features_js_1 = require("./ingestion/frameworks/spring/analysis-features.js");
+const analysis_features_js_2 = require("./ingestion/languages/java/analysis-features.js");
+const analysis_features_js_3 = require("./analysis-features.js");
+const analyzer_identity_js_1 = require("./analyzer-identity.js");
+/**
+ * Strip C0/C1 control characters from a progress/diagnostic message.
+ *
+ * Several guard notices below interpolate values read straight out of
+ * `.cgraphx/code/cgraph.json`, which is parsed with no runtime shape validation
+ * (`loadMeta` does a bare `JSON.parse(...) as RepoMeta`) — the stamped schema
+ * fingerprint, the runner-identity schema, the CJK mode. On the CLI path these
+ * reach `console.log` and therefore the user's terminal, so a crafted value
+ * carrying ANSI escapes (`\x1b[2J`, `\x1b]0;…`) would be replayed verbatim.
+ *
+ * Sanitizing at the funnel rather than per field: every message that ever
+ * interpolates untrusted metadata is covered, including ones not written yet.
+ * Newline and tab are preserved — multi-line notices are intentional.
+ */
+const stripControlCharacters = (msg) => msg.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g, '');
+const ANALYSIS_FEATURES = [
+    analysis_features_js_3.CLASS_FRAMEWORK_ANNOTATIONS_FEATURE,
+    analysis_features_js_1.SPRING_AOP_FEATURE,
+    analysis_features_js_1.SPRING_BEAN_INVENTORY_FEATURE,
+    analysis_features_js_1.SPRING_CONDITIONALS_FEATURE,
+    analysis_features_js_2.SPRING_CONFIG_BINDINGS_FEATURE,
+];
+function stringList(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === 'string')
+        : [];
+}
+function collectFrameworkAnnotationDriftFiles(graph, persistedRows) {
+    const persistedById = new Map();
+    for (const row of persistedRows) {
+        if (typeof row.id === 'string') {
+            persistedById.set(row.id, stringList(row.frameworkAnnotations));
+        }
+    }
+    const driftFiles = new Set();
+    graph.forEachNode((node) => {
+        if (node.label !== 'Class')
+            return;
+        const current = stringList(node.properties.frameworkAnnotations);
+        const persisted = persistedById.get(node.id) ?? [];
+        if (current.length !== persisted.length ||
+            current.some((annotation, index) => annotation !== persisted[index])) {
+            const filePath = node.properties.filePath;
+            if (typeof filePath === 'string')
+                driftFiles.add(filePath);
+        }
+    });
+    return driftFiles;
+}
+function collectSpringBeanDeclarationDriftFiles(graph, persistedRows) {
+    const persisted = new Map();
+    for (const row of persistedRows) {
+        if (typeof row.id === 'string' &&
+            typeof row.filePath === 'string' &&
+            typeof row.reason === 'string' &&
+            (0, bean_factories_js_1.isSpringBeanFactoryDeclaration)({ type: 'DECLARES', reason: row.reason })) {
+            persisted.set(row.id, { filePath: row.filePath, reason: row.reason });
+        }
+    }
+    const current = new Map();
+    for (const relationship of graph.relationships) {
+        if (relationship.type !== 'DECLARES')
+            continue;
+        if (!(0, bean_factories_js_1.isSpringBeanFactoryDeclaration)(relationship))
+            continue;
+        const declaration = graph.getNode(relationship.targetId);
+        if (declaration === undefined || typeof declaration.properties.filePath !== 'string')
+            continue;
+        current.set(declaration.id, {
+            filePath: declaration.properties.filePath,
+            reason: relationship.reason,
+        });
+    }
+    const driftFiles = new Set();
+    for (const [id, value] of current) {
+        const prior = persisted.get(id);
+        if (prior === undefined || prior.reason !== value.reason)
+            driftFiles.add(value.filePath);
+    }
+    for (const [id, value] of persisted) {
+        if (!current.has(id))
+            driftFiles.add(value.filePath);
+    }
+    return driftFiles;
+}
+exports.PHASE_LABELS = {
+    extracting: 'Scanning files',
+    structure: 'Building structure',
+    parsing: 'Parsing code',
+    imports: 'Resolving imports',
+    calls: 'Tracing calls',
+    heritage: 'Extracting inheritance',
+    scopeResolution: 'Resolving types',
+    communities: 'Detecting communities',
+    processes: 'Detecting processes',
+    complete: 'Pipeline complete',
+    lbug: 'Loading into LadybugDB',
+    embeddings: 'Generating embeddings',
+    done: 'Done',
+};
+// ---------------------------------------------------------------------------
+// Main orchestrator
+// ---------------------------------------------------------------------------
+/**
+ * Run the full GitNexus analysis pipeline.
+ *
+ * This is the shared core extracted from the CLI `analyze` command. It
+ * handles: pipeline execution, LadybugDB loading, embedding generation,
+ * metadata persistence, and AI context file generation.
+ *
+ * The function communicates progress and log messages exclusively through
+ * the {@link AnalyzeCallbacks} interface — it never writes to stdout/stderr
+ * directly and never calls `process.exit()`.
+ */
+/**
+ * Collect the recorded parse-cache chunk keys across the flat + every branch
+ * metadata directory under a flat `.cgraphx/code` storage, EXCLUDING `excludeDir`
+ * (the current run's own meta dir) so a single-branch repo collects nothing and
+ * its prune stays byte-identical to today (#2106 R6 — the byte-identity claim
+ * is about the PRUNE result; the metadata FILENAME read here changed with
+ * PR #2363's rename, checking `cgraph.json` first then the legacy
+ * `meta.json` mirror). `complete` is false when a sibling metadata file exists
+ * but fails to read or parse — callers then retain the whole shared cache
+ * rather than over-evict another branch's still-live shards. Exported for
+ * testing.
+ */
+const collectBranchCacheKeys = async (storagePath, excludeDir) => {
+    const keys = new Set();
+    let complete = true;
+    const metaDirs = [storagePath];
+    const branchesDir = path_1.default.join(storagePath, 'branches');
+    const slugs = await promises_1.default.readdir(branchesDir).catch(() => []);
+    for (const slug of slugs)
+        metaDirs.push(path_1.default.join(branchesDir, slug));
+    for (const dir of metaDirs) {
+        if (excludeDir && path_1.default.resolve(dir) === path_1.default.resolve(excludeDir))
+            continue;
+        let raw;
+        try {
+            raw = await promises_1.default.readFile(path_1.default.join(dir, repo_manager_js_1.INDEX_METADATA_FILE), 'utf-8');
+        }
+        catch (newErr) {
+            if (!(0, repo_manager_js_1.isMissingFilesystemError)(newErr)) {
+                complete = false;
+                continue;
+            }
+            try {
+                raw = await promises_1.default.readFile(path_1.default.join(dir, 'meta.json'), 'utf-8');
+            }
+            catch (legacyErr) {
+                if (!(0, repo_manager_js_1.isMissingFilesystemError)(legacyErr))
+                    complete = false;
+                continue; // no metadata here — not a branch index, not a failure
+            }
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed.cacheKeys)) {
+                for (const k of parsed.cacheKeys)
+                    if (typeof k === 'string')
+                        keys.add(k);
+            }
+        }
+        catch {
+            complete = false; // present but corrupt → fail-safe toward retention
+        }
+    }
+    return { keys, complete };
+};
+exports.collectBranchCacheKeys = collectBranchCacheKeys;
+/**
+ * Resolve whether streamed structural graph emit is on for this run (#2680).
+ *
+ * **On by default.** It costs nothing observable: the sink answers a complete
+ * relationship read, so community detection, process extraction and the
+ * local-symbol pruner all behave exactly as they do without it — the edges
+ * simply live in columns and on disk instead of as objects. There is no reason
+ * to make a user opt in to using less memory.
+ *
+ * Two conditions still bound it:
+ *
+ * - `force === true`. Sound only on a full rebuild (analyze is always a full
+ *   rebuild now, so every run qualifies once the freshness guards rebind
+ *   `options.force`).
+ * - `CGRAPH_STREAM_GRAPH_EMIT=0` (or an explicit `streamGraphEmit: false`)
+ *   turns it off. The escape hatch exists for bisecting a suspected
+ *   streaming-related fault, not as a routine choice.
+ *
+ * Read every call (not memoized) so `vi.stubEnv` works.
+ */
+const resolveStreamGraphEmit = (options) => {
+    if (options.force !== true)
+        return false;
+    if (options.streamGraphEmit !== undefined)
+        return options.streamGraphEmit;
+    // Unset ⇒ on. Set ⇒ honour it, so `=0` / `=false` is the escape hatch.
+    const raw = process.env.CGRAPH_STREAM_GRAPH_EMIT;
+    return raw === undefined || raw === '' ? true : (0, env_js_1.parseTruthyEnv)(raw);
+};
+exports.resolveStreamGraphEmit = resolveStreamGraphEmit;
+/**
+ * Resolve which storage slot this analyze writes to, including branch
+ * placement (#2106/#2354). Extracted from the top of the pipeline so the lock
+ * scope (`metaDir`) is known before the lock is acquired. Throws the same
+ * `--branch` / checked-out mismatch error the pipeline used to throw inline, so
+ * that failure still surfaces before any lock is taken.
+ */
+async function resolveWriteTarget(repoPath, options) {
+    // `storagePath` is ALWAYS the flat `.cgraphx/code` — content-addressed caches
+    // (parse-cache, parsedfile-store) and kuzu-migration cleanup live there and
+    // are shared across branches (#2106 KTD7).
+    const { storagePath } = (0, repo_manager_js_1.getStoragePaths)(repoPath);
+    const repoHasGit = (0, git_js_1.hasGitDir)(repoPath);
+    const currentCommit = repoHasGit ? (0, git_js_1.getCurrentCommit)(repoPath) : '';
+    // Normalize the auto-detected branch the same way an explicit `--branch` is
+    // validated (#2106 R1): a git ref the branch-name rules forbid becomes `null`
+    // → the flat slot, matching that a later `--branch <that-ref>` query would
+    // also be rejected. A normal ref round-trips index-time/query-time labels.
+    const checkedOutBranch = repoHasGit
+        ? ((0, analyze_config_js_1.sanitizeDetectedBranch)((0, git_js_1.getCurrentBranch)(repoPath)) ?? null)
+        : null;
+    // Analyze indexes the working tree, not an arbitrary ref. An explicit
+    // `--branch X` while a DIFFERENT branch Y is checked out would write Y's
+    // content into X's slot, corrupting X (#2106). Refuse the mismatch. Detached
+    // HEAD / non-git (checkedOutBranch === null) still allow an explicit label.
+    if (options.branch && checkedOutBranch && options.branch !== checkedOutBranch) {
+        throw new Error(`--branch "${options.branch}" does not match the checked-out branch "${checkedOutBranch}". ` +
+            `Check out "${options.branch}" before indexing it, or omit --branch to index the current branch.`);
+    }
+    const branchLabel = options.branch ?? checkedOutBranch;
+    const placement = options.branch ? await (0, repo_manager_js_1.resolveBranchPlacement)(repoPath, branchLabel) : {};
+    const { lbugPath, metaPath } = (0, repo_manager_js_1.getStoragePaths)(repoPath, placement.branch);
+    return {
+        storagePath,
+        repoHasGit,
+        currentCommit,
+        checkedOutBranch,
+        branchLabel,
+        placement,
+        lbugPath,
+        metaPath,
+        metaDir: path_1.default.dirname(metaPath),
+    };
+}
+/**
+ * Run the full analysis under an exclusive, index-directory-scoped write lock
+ * (#2658). A second concurrent `analyze` on the same slot waits here for the
+ * first to finish, then falls through to the normal freshness check inside —
+ * so a run whose work the holder already did returns `alreadyUpToDate` in
+ * seconds instead of rebuilding (single-flight coalescing), while a run for a
+ * genuinely-changed tree does one follow-up incremental. No new flag: waiting
+ * is the default, which is what hook-driven re-index wants.
+ *
+ * The lock is held by whichever process runs the pipeline (the heap-respawn
+ * child, or the original) — see index-lock.ts for why ownership lives with the
+ * writer, not a supervising parent. Released as soon as the write completes or
+ * throws; the post-analysis steps in the CLI (registry) run lock-free.
+ */
+async function runFullAnalysis(repoPath, options, callbacks, runnerIdentityAtBootstrap) {
+    // Scope the degraded-parse log throttle to this run (module-level counter
+    // would otherwise stay saturated on a reused process).
+    (0, safe_parse_js_1.resetDegradedParseCounter)();
+    // 早期加载 workspace 配置(spec §5.2 / §9):在触碰任何索引目录之前校验,
+    // 配置文件缺失 → 契约阶段跳过(返回 null);配置存在但解析/结构非法 → 抛
+    // WorkspaceConfigError 中止本次 analyze,不产出半索引。解析结果经进程缓存
+    // 供后续 rpc-edges / http-api-calls 阶段与 walker 复用(T-11 / T-12 接入消费)。
+    (0, workspace_config_js_1.loadWorkspaceConfig)(repoPath);
+    const log = (msg) => callbacks.onLog?.(stripControlCharacters(msg));
+    const acquireOpts = {
+        log,
+        onWaitStart: () => callbacks.onProgress('lock', 0, 'Waiting for another analyze to finish on this index…'),
+    };
+    let writeTarget = await resolveWriteTarget(repoPath, options);
+    let lock = await (0, index_lock_js_1.acquireIndexLock)(writeTarget.metaDir, acquireOpts);
+    try {
+        // #2658 review H2: acquireIndexLock can wait up to the timeout ceiling,
+        // during which git HEAD/branch — and thus the resolved write slot — may
+        // change (a commit lands, a branch is switched, or another writer adopts the
+        // flat slot). The pre-wait snapshot must NOT be reused: re-resolve UNDER the
+        // lock so the freshness check (`existingMeta.lastCommit === currentCommit`)
+        // and the meta stamps see current git state, honoring the module's "re-check
+        // freshness after acquiring" contract. If the slot itself moved we hold the
+        // WRONG lock — release and re-acquire the correct one. Bounded so a
+        // pathologically churning checkout can't loop forever; after the cap we
+        // proceed on the current lock. The loop is INSIDE the try so a re-resolve
+        // that throws (e.g. a `--branch` that stopped matching the now-switched
+        // checkout) still releases the held lock via `finally` (no leak).
+        const MAX_RELOCK = 3;
+        for (let attempt = 0; attempt < MAX_RELOCK; attempt++) {
+            const fresh = await resolveWriteTarget(repoPath, options);
+            if (fresh.metaDir === writeTarget.metaDir) {
+                writeTarget = fresh; // same slot — adopt the freshly-read commit/branch/placement
+                break;
+            }
+            log(`Index write target moved while waiting for the lock ` +
+                `(${writeTarget.metaDir} → ${fresh.metaDir}); re-acquiring the correct slot.`);
+            lock.release();
+            writeTarget = fresh;
+            lock = await (0, index_lock_js_1.acquireIndexLock)(fresh.metaDir, acquireOpts);
+            if (attempt === MAX_RELOCK - 1) {
+                log('Index write target still moving after repeated re-acquire; proceeding on this lock.');
+            }
+        }
+        return await runFullAnalysisInner(repoPath, options, callbacks, writeTarget, runnerIdentityAtBootstrap);
+    }
+    finally {
+        lock.release();
+    }
+}
+async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, runnerIdentityAtBootstrap) {
+    const log = (msg) => callbacks.onLog?.(stripControlCharacters(msg));
+    const progress = (phase, percent, message) => callbacks.onProgress(phase, percent, message);
+    // The degraded-parse counter reset happens in the `runFullAnalysis` wrapper
+    // (before the lock is taken).
+    // Write target (storage paths + resolved branch placement) was computed by
+    // the `runFullAnalysis` wrapper — which needs `metaDir` up front to acquire
+    // the exclusive index lock BEFORE any of the freshness/write work below
+    // (#2658). `storagePath` is ALWAYS the flat `.cgraphx/code`; `placement.branch`
+    // selects a `branches/<slug>/` sub-slot only for an explicit `--branch` that
+    // does not own the flat slot. See resolveWriteTarget for the full contract.
+    const { storagePath, repoHasGit, currentCommit, branchLabel, placement, lbugPath, metaDir } = writeTarget;
+    // Start each analyze with a clean buffer-pool hint: any pre-pipeline DB open
+    // (e.g. the embeddings-cache open) falls back to the default until the hint is
+    // set from the built graph below, so a prior run's size can't leak in.
+    (0, lbug_config_js_1.setBufferPoolSizeHint)(undefined);
+    // Clean up stale KuzuDB files from before the LadybugDB migration.
+    const kuzuResult = await (0, repo_manager_js_1.cleanupOldKuzuFiles)(storagePath);
+    if (kuzuResult.found && kuzuResult.needsReindex) {
+        log('Migrating from KuzuDB to LadybugDB — rebuilding index...');
+    }
+    // Keep cgraph.json and the legacy meta.json mirror in sync (fresher
+    // indexedAt wins; nothing is deleted). Best-effort: loadMeta has its own
+    // legacy fallback, so a reconciliation failure (read-only mount, full disk)
+    // must never abort the analyze run — a repo that indexed fine read-only
+    // before the rename must keep doing so.
+    try {
+        await (0, repo_manager_js_1.reconcileMetadataFiles)(repoPath);
+    }
+    catch (err) {
+        const code = err?.code;
+        log(`Metadata reconciliation failed (non-critical${code ? `, ${code}` : ''}); continuing.`);
+    }
+    const existingMeta = await (0, repo_manager_js_1.loadMeta)(metaDir);
+    // Resolve once per real analysis run so every successful metadata write
+    // carries one coherent receipt.
+    const runnerIdentity = runnerIdentityAtBootstrap ?? (0, analyzer_identity_js_1.resolveAnalyzerRunnerIdentity)((0, node_url_1.pathToFileURL)(__filename).href);
+    if (!(0, analyzer_identity_js_1.analyzerRunnerIdentitiesEqual)(runnerIdentity, runnerIdentity)) {
+        throw new Error('Analyzer bootstrap supplied a malformed runner identity receipt');
+    }
+    // ── Crash recovery: dirty flag forces full rebuild ────────────────
+    // If the previous incremental run set incrementalInProgress and didn't
+    // clear it, the on-disk index may be in a half-state. Cheapest path
+    // back to a known-good index is to wipe + rebuild from scratch.
+    if (existingMeta?.incrementalInProgress) {
+        const dirty = existingMeta.incrementalInProgress;
+        const dirtyDetails = typeof dirty === 'object'
+            ? [
+                dirty.phase ? `phase=${dirty.phase}` : undefined,
+                `toWrite=${dirty.toWriteCount}`,
+                dirty.importerExpansion !== undefined
+                    ? `importerExpansion=${dirty.importerExpansion}`
+                    : undefined,
+                dirty.effectiveWriteCount !== undefined
+                    ? `effectiveWrite=${dirty.effectiveWriteCount}`
+                    : undefined,
+                dirty.deleteCount !== undefined ? `deleteCount=${dirty.deleteCount}` : undefined,
+                // Only stamped when > 0 (tri-review 4669518496 P2-5): its
+                // presence means the crashed run's importer expansion was
+                // already degraded — the write set may have been under-expanded
+                // before the crash.
+                dirty.droppedImporterChunks !== undefined
+                    ? `droppedImporterChunks=${dirty.droppedImporterChunks}`
+                    : undefined,
+            ]
+                .filter(Boolean)
+                .join(', ')
+            : 'legacy dirty flag';
+        log(
+        // "analyze run", not "incremental run" — since #2099 F1 the flag is a
+        // generic dirty marker written by BOTH writeback branches.
+        'Previous analyze run did not complete cleanly (incrementalInProgress flag set); ' +
+            `last dirty state: ${dirtyDetails}; ` +
+            'forcing full rebuild to restore a known-good index.');
+        options = { ...options, force: true };
+        // Reload meta after clearing the flag in-memory; we still want fileHashes
+        // for the post-rebuild meta carry-over, but force=true ensures the
+        // rebuild path executes.
+        //
+        // #2409 defect 2: the crashed writeback's WAL can be poisoned — replaying
+        // it kills the process natively, and the first DB open of this recovery
+        // run (the embedding-cache preservation open below) happens BEFORE the
+        // rebuild wipe that would discard it. Park the WAL/shadow sidecars aside
+        // now, while nothing is open, so every open in this run is replay-free.
+        // The rebuild wipes the DB regardless, so no committed data is at stake.
+        const { removed, failed } = await (0, sidecar_recovery_js_1.quarantineSidecarsForDirtyRecovery)(lbugPath, log);
+        if (removed.length > 0) {
+            log(`Dirty-state recovery discarded ${removed.map((p) => path_1.default.basename(p)).join(', ')} ` +
+                'from the interrupted run (the file could not be moved aside, so its bytes were ' +
+                'removed — post-mortem forensics lost). Recovery proceeds with full embedding ' +
+                'preservation.');
+        }
+        if (failed.length > 0) {
+            // FIX 1 (this shipping review, replacing the tri-review 4669518496
+            // P2-3 drop-shape design): under a persistent lock the old drop-shape
+            // run derived its embedding mode as "drop", ran the WHOLE pipeline,
+            // and then died at the rebuild wipe on the very same handle — wasting
+            // minutes and zeroing embeddings on the way. A possibly-poisoned
+            // sidecar still sits next to the DB (any pre-wipe open would replay it
+            // and die), so failing here, in seconds, with the same actionable
+            // typed error the wipe would eventually throw is strictly better —
+            // and the CLI's LbugWipeError handler already renders it
+            // (recoveryHint 'lbug-wipe-failed'). The message is self-contained
+            // (headline + paths + lock guidance) because serve forwards only
+            // err.message over worker IPC.
+            throw new lbug_adapter_js_1.LbugWipeError(failed, {
+                headline: "Cannot start dirty-state recovery — the interrupted run's LadybugDB sidecars " +
+                    'could neither be moved aside nor removed:',
+            });
+        }
+    }
+    // ── schema mismatch forces full rebuild (#2289 P1, #2798) ─────────
+    // An index whose tables were created from a different DDL cannot be reconciled
+    // without a full rebuild — a same-commit re-analyze would strand stale rows
+    // next to new-schema writes, and LadybugDB fixes a relation table's endpoint
+    // pairs at CREATE time, so edges the old shape cannot hold are simply dropped.
+    // MUST sit before the alreadyUpToDate fast path below: an unchanged-commit
+    // clean tree would otherwise early-return without forcing the rebuild.
+    //
+    // Forcing here is what recreates the schema: `force` makes the run a full
+    // rebuild, which wipes the database file and re-runs the DDL against an
+    // empty one. Re-running `CREATE … TABLE` over the EXISTING database would
+    // not help — runSchemaCreationQueries suppresses "already exists", so the
+    // new shape would never be applied.
+    //
+    // ABSENT covers two cases and forces in both: an index from a GitNexus
+    // older than this field (the backward-compatibility path — one rebuild, then
+    // it is stamped), and a non-git repo, which never stamps it (see the meta
+    // literal below) and takes the `currentCommit === ''` rebuild branch below
+    // regardless.
+    //
+    // The two cases must not be told the same story. Blaming "an older GitNexus
+    // version" is FALSE for a non-git repo — the field is absent by design there,
+    // so this build would keep saying it about an index this exact build just
+    // wrote, on every run, forever. A stamp is only named when it has the shape
+    // SCHEMA_FINGERPRINT produces; anything else degrades to a neutral
+    // placeholder, and a non-git repo is additionally told WHY it has no stamp.
+    if (existingMeta && (0, schema_js_1.schemaFingerprintMismatch)(existingMeta.schemaFingerprint)) {
+        const stamped = existingMeta.schemaFingerprint;
+        const origin = (0, schema_js_1.isSchemaFingerprintShaped)(stamped) ? stamped : 'an unidentified GitNexus build';
+        const nonGitNote = stamped === undefined && !repoHasGit
+            ? ' Non-git repositories never record a schema fingerprint, so this run rebuilds regardless.'
+            : '';
+        log(`index schema changed (built by ${origin}, this build is ${schema_js_1.SCHEMA_FINGERPRINT}); forcing a ` +
+            `full re-analyze so the database is recreated from the current schema.${nonGitNote}`);
+        options = { ...options, force: true };
+    }
+    // ── independently-versioned analysis capabilities ────────────────
+    // `schemaFingerprint` is reserved for graph-wide incremental invariants. Some
+    // persisted semantics apply only to repositories containing relevant source
+    // files, so they carry exact feature versions instead. This guard must also
+    // run before alreadyUpToDate: a feature can change what is EXTRACTED without
+    // changing the DDL, so an index whose `schemaFingerprint` matches this build
+    // can still be missing that feature's evidence (e.g. the Class
+    // frameworkAnnotations values, or Java/Kotlin Bean evidence) — the fingerprint
+    // guard above would wave it through.
+    const persistedFilePaths = Object.keys(existingMeta?.fileHashes ?? {});
+    const expectedPersistedAnalysisFeatures = (0, analysis_features_js_3.resolveAnalysisFeatureVersions)(ANALYSIS_FEATURES, persistedFilePaths);
+    const persistedAnalysisFeatureMismatches = existingMeta
+        ? (0, analysis_features_js_3.findAnalysisFeatureMismatches)(existingMeta.analysisFeatures, expectedPersistedAnalysisFeatures)
+        : [];
+    let analysisFeatureMismatchLogged = false;
+    if (existingMeta && persistedAnalysisFeatureMismatches.length > 0) {
+        log(`analysis capabilities changed (${persistedAnalysisFeatureMismatches.join(', ')}); ` +
+            `forcing a full rebuild so persisted feature evidence is complete.`);
+        options = { ...options, force: true };
+        analysisFeatureMismatchLogged = true;
+    }
+    // Analyzer provenance is part of freshness, not merely diagnostics. A
+    // same-commit fast path must not preserve metadata produced by an older,
+    // malformed, or dependency/native-different runner. Force a real rebuild so
+    // the graph and its schema-v4 receipt are finalized atomically together.
+    if (existingMeta && !(0, analyzer_identity_js_1.analyzerRunnerIdentitiesEqual)(existingMeta.runnerIdentity, runnerIdentity)) {
+        const stampedRunnerSchema = existingMeta.runnerIdentity?.schemaVersion;
+        log(`analyzer runner identity changed (stamped schema ${String(stampedRunnerSchema ?? 'missing')}, ` +
+            `this build uses schema ${runnerIdentity.schemaVersion}); forcing a full rebuild so the ` +
+            'index provenance matches the analyzer and dependency/native runtime that produced it.');
+        options = { ...options, force: true };
+    }
+    // ── embedding width mismatch forces full rebuild (#2798) ──────────
+    // The half of the schema `SCHEMA_FINGERPRINT` deliberately cannot cover:
+    // `CodeEmbedding.embedding` is declared `FLOAT[EMBEDDING_DIMS]`, and that
+    // width comes from `CGRAPH_EMBEDDING_DIMS` at module load, so folding it
+    // into a digest of CODE would make the same build disagree with itself under
+    // two envs. Without this block a dims flip on a same-commit clean tree fired
+    // NO guard: the fast path below returned over a FLOAT[384] table while this
+    // process embedded at 768. The one older reaction (in the embedding-restore
+    // block further down) discards the CACHE and re-embeds — into a column whose
+    // width it never revisits.
+    //
+    // Forcing is again what repairs it, and for the same reason as the
+    // fingerprint guard: only a full rebuild wipes the database and re-runs the
+    // DDL, and `runSchemaCreationQueries` suppresses "already exists", so
+    // re-running CREATE over the existing DB would silently keep the old width.
+    // Not conditioned on the index actually holding vectors — the table is
+    // created for every index either way, and nothing but a rebuild can retype it.
+    //
+    // ABSENT is NOT a mismatch here (see embeddingDimsMismatch for the argument):
+    // it means an index predating the field, whose width is unknown but was
+    // consistent with the env that wrote it, and which the fingerprint guard
+    // above already rebuilds — that rebuild is where the stamp lands.
+    if (existingMeta && (0, schema_js_1.embeddingDimsMismatch)(existingMeta.embeddingDims, schema_js_1.EMBEDDING_DIMS)) {
+        // Only NAME a recorded width that could be one, for the reason the
+        // fingerprint guard gates its stamp on `isSchemaFingerprintShaped`:
+        // meta.json is a schema-less JSON.parse of on-disk state, so a value that
+        // is not a positive integer is not worth quoting back at the user.
+        const recordedDims = existingMeta.embeddingDims;
+        const built = typeof recordedDims === 'number' && Number.isInteger(recordedDims) && recordedDims > 0
+            ? `FLOAT[${recordedDims}]`
+            : 'an unrecognized width';
+        log(`embedding dimensions changed (index built with ${built}, this run embeds at ` +
+            `${schema_js_1.EMBEDDING_DIMS}); forcing a full rebuild so the vector column is recreated at the ` +
+            `new width. Tip: set CGRAPH_EMBEDDING_DIMS (or --embedding-dims) to pin it across runs.`);
+        options = { ...options, force: true };
+    }
+    // ── Early-return: already up to date ──────────────────────────────
+    if (existingMeta &&
+        !existingMeta.embeddingCheckpoint &&
+        !options.force &&
+        existingMeta.lastCommit === currentCommit) {
+        // Non-git folders have currentCommit = '' — always rebuild since we can't detect changes
+        if (currentCommit !== '') {
+            // For git repos, even if HEAD matches lastCommit, the working tree
+            // may have uncommitted changes. Only short-circuit when the working
+            // tree is also clean — otherwise fall through to the incremental
+            // path which will hash-diff and update only changed files.
+            //
+            // We exclude paths GitNexus writes during analyze plus the common
+            // AI-agent tooling artifacts (which analyze historically also wrote):
+            //   .cgraphx/                 — index storage (db / parse cache / meta.json under code/)
+            //   .claude/, .cursor/, .agents/ — agent tooling artifacts
+            //   AGENTS.md, CLAUDE.md        — agent instruction files
+            // Counting them as dirty would perpetually defeat the up-to-date
+            // fast path whenever agent tooling touches them
+            // (regression vs PR #1233 behavior).
+            const dirty = (0, git_js_1.isWorkingTreeDirty)(repoPath);
+            // Registration wrinkle around the fast path (#2264). A prior
+            // `analyze --name X` that hit a name collision writes meta.json (meta-save
+            // runs before registerRepo) then fails before registering, leaving the
+            // index up-to-date but UNREGISTERED. When the user re-runs with
+            // --allow-duplicate-name they explicitly want it registered, so fall
+            // through to the pipeline (which registers it, honoring the flag) instead
+            // of early-returning an unregistered repo the flag could never heal.
+            // For a PLAIN analyze we deliberately do NOT self-heal: an up-to-date but
+            // unregistered repo early-returns here and the CLI's assertAnalysisFinalized
+            // surfaces it as a hard failure (#1169) rather than silently registering a
+            // possibly half-finalized index. `isRepoRegistered` is only read on the
+            // opt-in branch so the common fast path keeps its single-stat cost.
+            const healUnregistered = options.allowDuplicateName === true && !(await (0, repo_manager_js_1.isRepoRegistered)(repoPath));
+            // Capability degradation is deliberately NOT self-healed here: an
+            // auto-heal probe would open the live index on the millisecond fast path
+            // and could turn this early return into a full re-analysis whenever an
+            // index authored under one capability set was later read on a host with
+            // another — a legitimate, common state, and the invariant
+            // `analyzer-identity-cli.test.ts` pins.
+            if (!dirty && !healUnregistered) {
+                // ── #2354: restamp the workspace label on a same-commit branch flip ──
+                // The flat slot follows the checked-out working tree; a branch switch
+                // at the SAME commit with a clean tree changes nothing the pipeline
+                // must rebuild, but the slot's informational `branch` label (and the
+                // registry copy that query-side branch scoping reads) would go stale.
+                // Detached HEAD / non-git (branchLabel === null) keeps the existing
+                // stamp, mirroring the end-of-run meta write.
+                if (!placement.branch && branchLabel && existingMeta.branch !== branchLabel) {
+                    // Adopt first, stamp last (#2364 review F3): this block's retry
+                    // guard is `existingMeta.branch !== branchLabel`, so stamping the
+                    // meta before the registry/shadow cleanup would flip the guard and
+                    // lock in any partial failure — with saveMeta last, a failed adopt
+                    // leaves the guard true and the next same-commit run self-heals
+                    // (adopt is idempotent). The whole sync is best-effort: the label
+                    // is informational and the flat DB content is byte-valid for both
+                    // labels here (same commit, clean tree), so an "Already up to
+                    // date" run must not fail over it; read-only storage — the
+                    // documented Docker :ro workflow (#1549) — degrades to a warning.
+                    try {
+                        await (0, repo_manager_js_1.adoptFlatBranchLabel)(repoPath, branchLabel);
+                        await (0, repo_manager_js_1.saveMeta)(metaDir, { ...existingMeta, branch: branchLabel });
+                    }
+                    catch (err) {
+                        // EACCES/EPERM also arise from ownership problems and transient
+                        // Windows locks, so keep the real error visible alongside the
+                        // #1549 read-only hint instead of replacing it.
+                        const reason = (0, repo_manager_js_1.isReadOnlyFilesystemError)(err)
+                            ? `${err.message} — storage may be read-only (#1549)`
+                            : err.message;
+                        log(`Warning: could not restamp the workspace branch label (${reason}); will retry on the next run.`);
+                    }
+                }
+                await (0, repo_manager_js_1.ensureGitNexusIgnored)(repoPath);
+                return {
+                    // `resolveRepoIdentityRoot` collapses worktree roots to the
+                    // canonical repo basename (#1259) but leaves arbitrary subdirs
+                    // and plain-folder roots unchanged.
+                    repoName: options.registryName ??
+                        (0, git_js_1.getInferredRepoName)(repoPath) ??
+                        path_1.default.basename((0, git_js_1.resolveRepoIdentityRoot)(repoPath)),
+                    repoPath,
+                    stats: existingMeta.stats ?? {},
+                    alreadyUpToDate: true,
+                    isPrimaryBranch: !placement.branch,
+                };
+            }
+        }
+    }
+    // ── Load incremental parse cache ──────────────────────────────────
+    // Content-addressed: safe to reuse across `--force` runs (chunks whose
+    // file contents haven't changed produce identical worker output).
+    // Loaded into a single ParseCache object that the pipeline mutates
+    // in-place (cache hits leave entries unchanged; misses add new ones).
+    const parseCache = await (0, parse_cache_js_1.loadParseCache)(storagePath);
+    // Streamed structural emit (#2680). Resolved ONCE, so the pipeline flag and
+    // the CSV-dir resolution below cannot disagree — and resolved HERE, not at
+    // function entry, because the POSITION is load-bearing: the gate is
+    // `options.force`, and every freshness guard above REBINDS `options` with
+    // `force: true` (dirty-flag recovery, schema-fingerprint change, analysis-
+    // feature drift, runner-identity change, CJK-mode change). Resolving before
+    // them froze the answer at `false` for every rebuild they trigger — including
+    // the whole-fleet rebuild a schema-fingerprint change forces on every existing
+    // index at once, which is exactly when the #2649 memory relief matters most.
+    // So this MUST stay below the last guard that can set `force` and above its
+    // first use.
+    const streamGraphEmitActive = (0, exports.resolveStreamGraphEmit)(options);
+    // ── Phase 1: Full Pipeline (0–60%) ────────────────────────────────
+    const pipelineResult = await (0, pipeline_js_1.runPipelineFromRepo)(repoPath, (p) => {
+        const phaseLabel = exports.PHASE_LABELS[p.phase] || p.phase;
+        const scaled = Math.round(p.percent * 0.6);
+        const message = p.detail
+            ? `${p.message || phaseLabel} (${p.detail})`
+            : p.message || phaseLabel;
+        progress(p.phase, scaled, message);
+    }, {
+        parsedFileStorePath: storagePath,
+        parseCache,
+        workerPoolSize: options.workerPoolSize,
+        // Streamed structural emit (#2680) — gated to full-rebuild runs.
+        streamGraphEmit: streamGraphEmitActive,
+        graphEmitCsvDir: streamGraphEmitActive
+            ? (0, lbug_config_js_1.resolveNativeSafeStorageDir)(storagePath, 'graph-csv')
+            : undefined,
+        fetchWrappers: options.fetchWrappers,
+    });
+    // ── Phase 2: LadybugDB (60–85%) ──────────────────────────────────
+    progress('lbug', 60, 'Loading into LadybugDB...');
+    // Compute current per-file content hashes from the pipeline's File nodes.
+    // Used both to drive the incremental DB writeback (when eligible) and to
+    // populate meta.json.fileHashes for the next run.
+    const allFilePaths = [];
+    pipelineResult.graph.forEachNode((n) => {
+        if (n.label === 'File') {
+            const fp = n.properties?.filePath;
+            if (fp)
+                allFilePaths.push(fp);
+        }
+    });
+    const newFileHashes = await (0, file_hash_js_1.computeFileHashes)(repoPath, allFilePaths);
+    const currentAnalysisFeatures = (0, analysis_features_js_3.resolveAnalysisFeatureVersions)(ANALYSIS_FEATURES, allFilePaths);
+    const currentAnalysisFeatureMismatches = existingMeta
+        ? (0, analysis_features_js_3.findAnalysisFeatureMismatches)(existingMeta.analysisFeatures, currentAnalysisFeatures)
+        : [];
+    if (existingMeta &&
+        currentAnalysisFeatureMismatches.length > 0 &&
+        !analysisFeatureMismatchLogged) {
+        // Covers a repository gaining or losing its first applicable source file:
+        // the persisted file list cannot predict that transition before the
+        // pipeline, but an incremental top-up would leave unchanged rows incomplete.
+        log(`analysis capabilities changed (${currentAnalysisFeatureMismatches.join(', ')}); ` +
+            `forcing a full rebuild so persisted feature evidence is complete.`);
+        options = { ...options, force: true };
+    }
+    // #2 atomic index publish: on a full rebuild, build the fresh DB at a temp
+    // path and swap it over the live index in one rename at the very end, so a
+    // concurrent MCP reader opening mid-build only ever sees the previous
+    // complete index (never a wiped/half-built file) and a crash leaves the old
+    // index intact. The whole build flows through the singleton connection, so
+    // only initLbug/wipeLbugDbFiles below take the temp target.
+    //
+    // POSIX only: the common CLI/serve-worker analyze paths skip the native close
+    // (closeLbugBeforeExit, #2264) and leave the build handle open at swap time.
+    // POSIX renames an open file cleanly; a same-process open handle blocks the
+    // rename on Windows. Windows keeps the current in-place behavior
+    // (buildPath === lbugPath, no swap) until that is resolved (see §12/follow-up).
+    //
+    // Analyze is always a full rebuild now (incremental writeback was removed),
+    // so every run qualifies for the swap where the platform allows.
+    // Where the swap is allowed:
+    //  - POSIX renames an open file, so the usual skip-native-close (#2264) is
+    //    fine and the swap always applies.
+    //  - Windows can swap only when a real close is safe to release the build
+    //    handle before the rename. Unverified on Windows CI; falls back to
+    //    in-place otherwise. Keep it opt-in (CGRAPH_ATOMIC_WINDOWS_SWAP=1) so the
+    //    default Windows analyze stays on the proven in-place path.
+    const posixSwap = process.platform !== 'win32';
+    const windowsSwapOk = process.platform === 'win32' && process.env.CGRAPH_ATOMIC_WINDOWS_SWAP === '1';
+    const useAtomicSwap = posixSwap || windowsSwapOk;
+    // #2658: a per-run staging name (was the fixed `lbug.new`). Even under the
+    // single-writer lock, a unique name means a crashed run's half-built staging
+    // file can never be mistaken for — or clobber — a live run's; the lock's
+    // orphan sweep (sweepStagingArtifacts) reclaims stragglers on the next
+    // acquire. The `.staging.` prefix is what that sweep matches.
+    const buildPath = useAtomicSwap ? `${lbugPath}.staging.${(0, node_crypto_1.randomUUID)()}` : lbugPath;
+    // Full rebuild path: wipe DB files first.
+    // Set the dirty flag BEFORE the wipe whenever a prior meta exists. Without it
+    // a full rebuild crashing between the wipe and the end-of-run saveMeta leaves
+    // a meta that vouches for a DB it no longer matches — the next clean-tree
+    // run's fast path would certify a destroyed DB. toWriteCount: 0 is the
+    // full-path sentinel.
+    if (existingMeta) {
+        const now = Date.now();
+        await (0, repo_manager_js_1.saveMeta)(metaDir, {
+            ...existingMeta,
+            incrementalInProgress: {
+                startedAt: now,
+                updatedAt: now,
+                phase: 'full-rebuild',
+                toWriteCount: 0,
+            },
+        });
+    }
+    await (0, lbug_adapter_js_1.closeLbug)();
+    // Shared loud wipe (#2409 + tri-review 4669518496 P2-4). The 4-file
+    // family list — `.shadow` included, because a checkpoint-in-flight crash
+    // leaves a shadow sidecar that is replay poison next to a freshly created
+    // DB file — lives in wipeLbugDbFiles so this site can never drift. Failures
+    // now throw a typed LbugWipeError (ENOENT-verified removal) instead of
+    // silently letting initLbug reopen a still-populated DB this run believes it
+    // wiped.
+    //
+    // With the atomic swap (POSIX), this wipes the TEMP build target
+    // (`buildPath` = `<lbugPath>.new`, clearing any stragglers from a crashed
+    // run) and leaves the live index untouched until the end-of-run swap. On
+    // Windows buildPath === lbugPath, so this is the original in-place wipe.
+    await (0, lbug_adapter_js_1.wipeLbugDbFiles)(buildPath);
+    // Size the buffer pool to the graph just built by the pipeline (a page cache
+    // over the on-disk index, which scales with node/edge count) instead of the
+    // fixed 2 GiB default, whose eager commit dominates large-repo analyze. The
+    // size is clamped to [COPY-safety floor, default], so it only ever shrinks
+    // the pool; env override / no-hint paths are unchanged. See
+    // resolveBufferManagerSize / estimateBufferPool.
+    (0, lbug_config_js_1.setBufferPoolSizeHint)((0, lbug_config_js_1.estimateBufferPool)(pipelineResult.graph.nodeCount +
+        pipelineResult.graph.relationshipCount +
+        // Streamed edges left the heap but still get COPYed, so they are part of
+        // the real load volume (#2680). The hint only ever SHRINKS the pool, so
+        // omitting them would starve the COPY at exactly the scale streaming
+        // exists to serve.
+        (pipelineResult.graphEmitManifest?.totalRows ?? 0)));
+    // Full rebuild (POSIX) builds into the temp `buildPath`; Windows uses
+    // `buildPath === lbugPath` in place.
+    await (0, lbug_adapter_js_1.initLbug)(buildPath);
+    // Manual WAL checkpoint driver (#1741): periodically drain the WAL
+    // from JS so the un-retriable native auto-checkpoint almost never
+    // has work left to do. Failures of the manual CHECKPOINT are absorbed
+    // by the driver's bounded retry; the final un-recoverable error still
+    // surfaces via the surrounding write that follows the failed flush.
+    // Opt-out via `CGRAPH_WAL_MANUAL_CHECKPOINT=0` (the driver itself
+    // returns a no-op handle when disabled). Analyze-only: MCP and serve
+    // paths continue to rely on the close-time CHECKPOINT in `safeClose`.
+    const walCheckpointDriver = (0, wal_checkpoint_driver_js_1.startWalCheckpointDriver)();
+    try {
+        // All work after initLbug is wrapped in try/finally to ensure closeLbug()
+        // is called even if an error occurs — the module-level singleton DB handle
+        // must be released to avoid blocking subsequent invocations.
+        let lbugMsgCount = 0;
+        // ── Full rebuild ───────────────────────────────────────────────
+        // Pass the streamed structural graph emit (#2680) so the rows flushed
+        // to CSV during the emit loop are COPY'd alongside the rest.
+        await (0, lbug_adapter_js_1.loadGraphToLbug)(pipelineResult.graph, pipelineResult.repoPath, storagePath, (msg) => {
+            lbugMsgCount++;
+            const pct = Math.min(84, 60 + Math.round((lbugMsgCount / (lbugMsgCount + 10)) * 24));
+            progress('lbug', pct, msg);
+        }, pipelineResult.graphEmitManifest);
+        const stats = await (0, lbug_adapter_js_1.getLbugStats)();
+        // ── Phase 5: Finalize (98–100%) ───────────────────────────────────
+        progress('done', 98, 'Saving metadata...');
+        const { getRuntimeCapabilities } = await import('./platform/capabilities.js');
+        const runtimeCapabilities = getRuntimeCapabilities();
+        // Convert the post-run file-hash map to the on-disk Record<string,string>
+        // shape consumed by RepoMeta.fileHashes.
+        const newFileHashesRecord = {};
+        for (const [k, v] of newFileHashes)
+            newFileHashesRecord[k] = v;
+        const resolutionOutcomes = pipelineResult.resolutionOutcomes ?? [];
+        (0, unresolved_receivers_js_1.logUnresolvedReceiverFiles)(resolutionOutcomes);
+        // Annotated so the capabilities stamp below is compile-checked against
+        // RepoMeta's status unions (tri-review 4669518496 P1/U3) — an unannotated
+        // literal widens the vectorSearch.status ternary to `string` and the
+        // honesty contract silently decays to "whatever interpolates".
+        const meta = {
+            repoPath,
+            lastCommit: currentCommit,
+            indexedAt: new Date().toISOString(),
+            runnerIdentity,
+            // Branch identity this index represents (#2106). Recorded for the flat
+            // slot too (so resolveBranchPlacement knows which branch owns it). When
+            // the label is null (detached HEAD / non-git re-analyze) we PRESERVE an
+            // existing stamp rather than stripping it — otherwise a detached re-index
+            // of the primary (e.g. CI's `actions/checkout` default) would un-claim the
+            // flat slot and let the next branch analyze overwrite the primary index.
+            // Stays absent only when never stamped (fresh detached/non-git repo).
+            branch: branchLabel ?? existingMeta?.branch,
+            // Captured here (not at registration) so it travels with the
+            // on-disk meta.json — sibling-clone fingerprinting works for
+            // out-of-tree consumers (group-status, future tooling) without
+            // a second git shellout. `undefined` when the repo has no
+            // origin remote, which is fine: paths-only repos behave as
+            // before.
+            remoteUrl: (0, git_js_1.hasGitDir)(repoPath) ? (0, git_js_1.getRemoteUrl)(repoPath) : undefined,
+            stats: {
+                files: pipelineResult.totalFileCount,
+                nodes: stats.nodes,
+                edges: stats.edges,
+                communities: pipelineResult.communityResult?.stats.totalCommunities,
+                processes: pipelineResult.processResult?.stats.totalProcesses,
+                embeddings: 0,
+            },
+            capabilities: {
+                graph: { provider: 'ladybugdb', status: runtimeCapabilities.graph },
+                vectorSearch: {
+                    // Embeddings were removed from this build, so the vector lane is
+                    // never populated.
+                    provider: 'exact-scan',
+                    status: 'unavailable',
+                    exactScanLimit: runtimeCapabilities.exactScanLimit,
+                    reason: runtimeCapabilities.reason,
+                },
+            },
+            // Derived digest of the DDL this run created the tables from (#2798).
+            // Git-only: non-git repos never take the incremental path.
+            schemaFingerprint: (0, git_js_1.hasGitDir)(repoPath) ? schema_js_1.SCHEMA_FINGERPRINT : undefined,
+            unresolvedReceiverMembers: (0, unresolved_receivers_js_1.summarizeUnresolvedReceivers)(resolutionOutcomes),
+            analysisFeatures: currentAnalysisFeatures,
+            // The FLOAT[N] width this run created the vector column at (#2798).
+            // Always stamped, unlike `schemaFingerprint`: the CodeEmbedding table is
+            // created for every index, git or not, so absence has exactly one
+            // meaning — an index older than the field.
+            embeddingDims: schema_js_1.EMBEDDING_DIMS,
+            fileHashes: (0, git_js_1.hasGitDir)(repoPath) ? newFileHashesRecord : undefined,
+            // This branch's full live chunk-key set (#2106 R6). `usedKeys` is every
+            // chunk hash touched in this scan — cache HITS included (see parse-impl
+            // usedKeys.add) — so it's complete even on an incremental run. Persisted
+            // so a sibling branch's prune can union it and not evict our shards.
+            cacheKeys: [...parseCache.usedKeys],
+            // Setting incrementalInProgress to undefined explicitly clears any prior
+            // dirty flag set during this run's full-rebuild wipe.
+            incrementalInProgress: undefined,
+            // Embeddings checkpoint is always cleared on a clean run (embeddings are
+            // no longer generated by this build).
+            embeddingCheckpoint: undefined,
+        };
+        // Re-resolve at the commit boundary. Long analyses can overlap an npm
+        // upgrade, rebuilt dist tree, or native dependency replacement; stamping
+        // the start-of-run receipt after such a mutation would falsely certify a
+        // graph produced by two analyzer identities. Stable-read validation lives
+        // inside the resolver, and a mismatch leaves the dirty flag intact so the
+        // next run takes the established full-recovery path.
+        meta.runnerIdentity = (0, analyzer_identity_js_1.finalizeAnalyzerRunnerIdentity)((0, node_url_1.pathToFileURL)(__filename).href, runnerIdentity);
+        // #2614 F1: the freshness stamp (saveMeta) is written AFTER the atomic swap
+        // below — never here — so a concurrent MCP reader can't observe
+        // meta.indexedAt = T_new while lbugPath still resolves to the pre-swap
+        // inode (which latched the reader on the stale index permanently). The meta
+        // object is fully computed at this point; only its write is deferred.
+        // Persist the incremental parse cache for the next run. Wraps in
+        // try/catch so a cache-write failure never breaks an otherwise
+        // successful indexing run. Prune stale chunk-hash entries first so
+        // the cache file size stays bounded across runs (chunks whose
+        // composition no longer matches anything in the current scan are
+        // dead weight; the parse phase populates `usedKeys` as it processes
+        // chunks).
+        try {
+            // #2106 R6: the parse cache + durable store are shared across branches.
+            // Before pruning to this run's keys, fold in the OTHER branches' recorded
+            // chunk keys so a branch switch doesn't evict their still-live shards.
+            // Adding to usedKeys makes them survive pruneCache AND land in the saved
+            // index (saveParseCache builds the index from usedKeys). Excludes this
+            // run's own meta dir, so a single-branch repo folds in nothing → prune
+            // set byte-identical to today.
+            const { keys: siblingKeys, complete } = await (0, exports.collectBranchCacheKeys)(storagePath, metaDir);
+            if (complete) {
+                for (const k of siblingKeys)
+                    parseCache.usedKeys.add(k);
+            }
+            else {
+                // Fail-safe toward retention: a sibling meta was unreadable, so keep
+                // everything currently loaded rather than evict on incomplete info.
+                log('Parse cache: a branch meta was unreadable — retaining all cached chunks (#2106).');
+                for (const k of parseCache.entries.keys())
+                    parseCache.usedKeys.add(k);
+            }
+            const pruned = (0, parse_cache_js_1.pruneCache)(parseCache, parseCache.usedKeys);
+            if (pruned > 0) {
+                log(`Parse cache: pruned ${pruned} stale chunk entries`);
+            }
+            const savedKeys = await (0, parse_cache_js_1.saveParseCache)(storagePath, parseCache);
+            // Prune the durable ParsedFile store to EXACTLY the parse cache's
+            // surviving keys (#2038 warm-cache coverage), so the two content-addressed
+            // stores stay coherent: a chunk is "cached" iff both its parse-cache shard
+            // and its durable shards exist. A quarantined chunk (in usedKeys but with
+            // no parse-cache shard) drops its durable subdir here and re-dispatches
+            // next run. Same try/catch — a durable-store write failure must never
+            // break an otherwise successful run (next run treats it as a miss).
+            await (0, parsedfile_store_js_1.pruneAndSaveDurableParsedFileStore)((0, parsedfile_store_js_1.getDurableParsedFileDir)(storagePath), parse_cache_js_1.PARSE_CACHE_VERSION, new Set(savedKeys));
+        }
+        catch (e) {
+            log(`Warning: could not save parse cache (${e.message}); continuing.`);
+        }
+        // Forward the --name alias and the registry-collision bypass bit.
+        // `allowDuplicateName` is its own concern — independent from the
+        // pipeline `force` above. The CLI maps it from
+        // `--allow-duplicate-name` only; `--force` triggers a pipeline re-run
+        // but never bypasses the registry guard. The returned name is the one
+        // actually written to the registry (after applying the precedence chain
+        // in registerRepo) (#979).
+        const projectName = await (0, repo_manager_js_1.registerRepo)(repoPath, meta, {
+            name: options.registryName,
+            allowDuplicateName: options.allowDuplicateName,
+            // Non-primary branch runs upsert into the entry's branches[]; the
+            // primary/flat run (placement.branch === undefined) refreshes the
+            // top-level fields (#2106).
+            branch: placement.branch,
+        });
+        // ── #2354: the flat workspace slot has adopted this run's branch ──────
+        // Drop a now-shadowed `branches/<slug>/` sub-index for the same label
+        // (unreachable once the flat slot serves it) and align the registry's
+        // top-level branch label. Best-effort like the parse-cache save above
+        // (#2364 review F5): the index is complete and registered, and a failure
+        // here leaves only a stale registry label / undeleted shadowed dir —
+        // never wrong routing, because the flat meta this run already stamped is
+        // what applyBranchScope trusts. Retried by the next content-changing run
+        // (same-commit fast-path runs skip it: their guard compares the
+        // already-stamped meta label).
+        if (!placement.branch && branchLabel) {
+            try {
+                await (0, repo_manager_js_1.adoptFlatBranchLabel)(repoPath, branchLabel);
+            }
+            catch (e) {
+                log(`Warning: could not sync the workspace branch label (${e.message}); continuing.`);
+            }
+        }
+        // Keep generated .cgraphx/code contents ignored without editing the user's root .gitignore.
+        await (0, repo_manager_js_1.ensureGitNexusIgnored)(repoPath);
+        // ── Close LadybugDB ──────────────────────────────────────────────
+        // Stop the manual checkpoint driver before closeLbug so its
+        // in-flight CHECKPOINT cannot race the `safeClose` CHECKPOINT.
+        await walCheckpointDriver.stop();
+        // CLI callers (about to process.exit) skip the native close —
+        // closeLbugBeforeExit CHECKPOINTs for durability then leaves the handles for
+        // process exit to reclaim (#2264). Long-lived callers close for real.
+        //
+        // On Windows a swap must release the build handle before the rename (a
+        // same-process open file can't be renamed), so it forces a real close.
+        // POSIX renames an open file, so it keeps the skip-native-close there.
+        const forceRealCloseForSwap = useAtomicSwap && process.platform === 'win32';
+        await (options.skipNativeCloseOnExit && !forceRealCloseForSwap
+            ? (0, lbug_adapter_js_1.closeLbugBeforeExit)()
+            : (0, lbug_adapter_js_1.closeLbug)());
+        // #2 atomic publish: the fresh index was built at buildPath (always a full
+        // rebuild now). Swap it over the live lbugPath in one rename so an MCP
+        // reader that opened mid-build only ever saw the previous complete index —
+        // never a wiped/half-built file. The close above checkpoint-consolidated
+        // buildPath to a single file (no .wal), so the rename publishes a complete
+        // index; a reader holding the old inode keeps a consistent stale snapshot
+        // until the pool re-opens onto the new one (the pool staleness
+        // invalidation). Runs only on success — a thrown error skips this, leaving
+        // the live index intact and the temp build to be cleared by the next run's
+        // wipe.
+        // Only publish if the build actually produced a DB at buildPath. A
+        // degenerate run (empty repo, or a mocked pipeline that never opened the
+        // store) leaves nothing to swap — skip rather than throw ENOENT.
+        const builtDbExists = useAtomicSwap
+            ? await promises_1.default.stat(buildPath).then(() => true, () => false)
+            : false;
+        if (useAtomicSwap && builtDbExists) {
+            await (0, fs_atomic_js_1.retryRename)(buildPath, lbugPath);
+            // Clear any sidecars orphaned beside the replaced file. A cleanly-closed
+            // prior index has none; a crashed one could, and it would be replay
+            // poison next to the freshly published index. Best-effort.
+            for (const suffix of ['.wal', '.shadow', '.wal.checkpoint']) {
+                await promises_1.default.rm(`${lbugPath}${suffix}`, { force: true }).catch(() => { });
+            }
+            // #2614 F4: if the final checkpoint silently failed, the build may still
+            // carry a residual .wal/.shadow under the temp name. MOVE it beside the
+            // published index (not orphan/delete it) so the next open replays the
+            // delta, rather than leaving it under a name LadybugDB never reconciles.
+            for (const suffix of ['.wal', '.shadow']) {
+                await promises_1.default.rename(`${buildPath}${suffix}`, `${lbugPath}${suffix}`).catch(() => { });
+            }
+        }
+        // #2614 F1: stamp the freshness metadata now that the index is published.
+        // When meta.indexedAt becomes visible, lbugPath already resolves to the new
+        // inode, so a reader reiniting on the stamp opens the fresh graph rather
+        // than latching on the old one. Leaving the dirty flag set across the swap
+        // is a crash-safety improvement: a failed swap leaves the previous index
+        // live and the next run recovers via the full-rebuild path.
+        await (0, repo_manager_js_1.saveMeta)(metaDir, meta);
+        progress('done', 100, 'Done');
+        return {
+            repoName: projectName,
+            repoPath,
+            stats: meta.stats,
+            pipelineResult,
+            isPrimaryBranch: !placement.branch,
+        };
+    }
+    catch (err) {
+        // Ensure LadybugDB is closed even on error. Stop the driver first
+        // so its retry loop cannot extend an already-failing analyze.
+        try {
+            await walCheckpointDriver.stop();
+        }
+        catch {
+            /* swallow — surface path is the rethrow below */
+        }
+        try {
+            // Skip the native close on the error path too: a real conn.close() after
+            // large --pdg writes can itself abort in LadybugDB's ClientContext
+            // destructor (#2264 review P2), turning an actionable exit-1 into a raw
+            // SIGABRT. closeLbugBeforeExit leaves the handles open, but the CLI catch
+            // now force-exits when isLbugReady() (analyze.ts, #2264 review P1), so the
+            // process still terminates — no hang, no abort. flushWAL keeps the partial
+            // index durable; process exit reclaims the handles. Long-lived callers
+            // (skipNativeCloseOnExit unset) close for real.
+            await (options.skipNativeCloseOnExit ? (0, lbug_adapter_js_1.closeLbugBeforeExit)() : (0, lbug_adapter_js_1.closeLbug)());
+        }
+        catch {
+            /* swallow */
+        }
+        // Reclaim the staging index this run created (#2841 cleanup). Without this
+        // a failed staged build orphans a FULL copy of the index — hundreds of MB on
+        // a large repo — until the next `acquireIndexLock` sweeps `lbug.staging.`
+        // artifacts, and the failure most likely to leave one (a machine whose
+        // extension cannot load) is also the one least likely to be followed by
+        // another analyze. Only ever removes a path this run minted: `buildPath`
+        // differs from `lbugPath` exactly when the atomic-swap plan is in effect,
+        // and the live index is never that path. Best-effort by construction — the
+        // rethrow below is the surface, and the lock's sweep remains the backstop.
+        if (useAtomicSwap && buildPath !== lbugPath) {
+            try {
+                await (0, lbug_adapter_js_1.wipeLbugDbFiles)(buildPath);
+            }
+            catch {
+                /* swallow — orphan reclamation must never mask the real failure */
+            }
+        }
+        throw err;
+    }
+}