@codragraph/cli 1.6.3 → 2.0.0

package/dist/core/run-analyze.js

@@ -10,9 +10,11 @@
  */
 import path from 'path';
 import fs from 'fs/promises';
+import * as fsSync from 'node:fs';
+import * as v8 from 'node:v8';
 import { runPipelineFromRepo } from './ingestion/pipeline.js';
 import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, loadCachedEmbeddings, } from './lbug/lbug-adapter.js';
-import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, cleanupOldKuzuFiles, } from '../storage/repo-manager.js';
+import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, cleanupOldKuzuFiles, INDEX_SCHEMA_VERSION, } from '../storage/repo-manager.js';
 import { getCurrentCommit, getRemoteUrl, hasGitDir, getInferredRepoName } from '../storage/git.js';
 import { recordAnalysisSnapshot } from './graphstore/index.js';
 import { generateAIContextFiles } from '../cli/ai-context.js';
@@ -51,7 +53,70 @@ export const PHASE_LABELS = {
  */
 export async function runFullAnalysis(repoPath, options, callbacks) {
     const log = (msg) => callbacks.onLog?.(msg);
-    const progress = (phase, percent, message) => callbacks.onProgress(phase, percent, message);
+    // RFC 0002 Phase 1 — optional heap-profile instrumentation. Set
+    // CODRAGRAPH_HEAP_PROFILE=1 (or run `codragraph profile-heap`) to write a
+    // v8 heap snapshot at every phase boundary, plus a `profile-summary.jsonl`
+    // log of `process.memoryUsage()` at the same boundaries. Snapshots land in
+    // `<repo>/.codragraph/heap-profiles/`. Open snapshots in Chrome DevTools
+    // (Memory → Load) to find which constructors dominate retained set; the
+    // JSONL is the cheap RSS / heapUsed timeline. Off by default — snapshot
+    // writes pause the event loop ~2-5s and consume ~100-500MB of disk each.
+    const heapProfileEnabled = process.env.CODRAGRAPH_HEAP_PROFILE === '1';
+    let heapProfileDir = '';
+    let heapProfileSummaryPath = '';
+    let lastProfilePhase = '';
+    if (heapProfileEnabled) {
+        heapProfileDir = path.join(repoPath, '.codragraph', 'heap-profiles');
+        heapProfileSummaryPath = path.join(heapProfileDir, 'profile-summary.jsonl');
+        try {
+            fsSync.mkdirSync(heapProfileDir, { recursive: true });
+            // Truncate any prior summary so a single run produces a clean log.
+            // We append crash-safely on each phase boundary below.
+            fsSync.writeFileSync(heapProfileSummaryPath, '');
+        }
+        catch {
+            /* permission issue — best-effort */
+        }
+    }
+    const progress = (phase, percent, message) => {
+        callbacks.onProgress(phase, percent, message);
+        // Only snapshot on phase transitions, not every tick. Phase strings come
+        // from runPipelineFromRepo / loadGraphToLbug and are stable.
+        if (heapProfileEnabled && phase && phase !== lastProfilePhase) {
+            lastProfilePhase = phase;
+            const ts = Date.now();
+            const safe = phase.replace(/[^a-zA-Z0-9]+/g, '_').slice(0, 60);
+            const file = path.join(heapProfileDir, `${ts}-${safe}.heapsnapshot`);
+            // Capture the cheap memoryUsage timeline FIRST — even if writeHeapSnapshot
+            // crashes (out of disk, permissions), we still have the RSS curve which
+            // is the more useful artifact for the heap-pressure RFC.
+            try {
+                const mu = process.memoryUsage();
+                const entry = JSON.stringify({
+                    ts,
+                    phase,
+                    percent,
+                    rss: mu.rss,
+                    heapUsed: mu.heapUsed,
+                    heapTotal: mu.heapTotal,
+                    external: mu.external,
+                    arrayBuffers: mu.arrayBuffers,
+                    snapshotFile: path.basename(file),
+                });
+                fsSync.appendFileSync(heapProfileSummaryPath, entry + '\n');
+            }
+            catch (err) {
+                log(`heap-profile: summary append failed (${err.message})`);
+            }
+            try {
+                v8.writeHeapSnapshot(file);
+                log(`heap-profile: wrote ${file}`);
+            }
+            catch (err) {
+                log(`heap-profile: write failed (${err.message})`);
+            }
+        }
+    };
     const { storagePath, lbugPath } = getStoragePaths(repoPath);
     // Clean up stale KuzuDB files from before the LadybugDB migration.
     const kuzuResult = await cleanupOldKuzuFiles(storagePath);
@@ -62,7 +127,17 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     const currentCommit = repoHasGit ? getCurrentCommit(repoPath) : '';
     const existingMeta = await loadMeta(storagePath);
     // ── Early-return: already up to date ──────────────────────────────
-    if (existingMeta && !options.force && existingMeta.lastCommit === currentCommit) {
+    // Schema-version mismatch forces a full re-analyze regardless of commit
+    // equality: existing 1.7.x indexes have no `schemaVersion` field at all,
+    // and 1.8+ readers expect every node table to carry a `contentEncoding`
+    // column (RFC 0001 Phase 2). LadybugDB ALTER on existing tables is not
+    // validated end-to-end yet, so the supported migration path is
+    // re-analyze → fresh CREATE NODE TABLE.
+    const schemaUpToDate = !!existingMeta && (existingMeta.schemaVersion ?? 0) >= INDEX_SCHEMA_VERSION;
+    if (existingMeta &&
+        schemaUpToDate &&
+        !options.force &&
+        existingMeta.lastCommit === currentCommit) {
         // Non-git folders have currentCommit = '' — always rebuild since we can't detect changes
         if (currentCommit !== '') {
             return {
@@ -73,6 +148,11 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             };
         }
     }
+    if (existingMeta && !schemaUpToDate) {
+        log(`Index schema version ${existingMeta.schemaVersion ?? '<missing>'} is older than ` +
+            `${INDEX_SCHEMA_VERSION} (RFC 0001 Phase 2 — adds contentEncoding column). ` +
+            `Re-analyzing.`);
+    }
     // ── Cache embeddings from existing index before rebuild ────────────
     let cachedEmbeddingNodeIds = new Set();
     let cachedEmbeddings = [];
@@ -122,7 +202,12 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             lbugMsgCount++;
             const pct = Math.min(84, 60 + Math.round((lbugMsgCount / (lbugMsgCount + 10)) * 24));
             progress('lbug', pct, msg);
-        });
+        }, 
+        // RFC 0001 Phase 2: when --compress is set, every content row goes
+        // through encodeContent before hitting the CSV. Default 'none' is
+        // a true passthrough, so the on-disk layout is byte-identical to
+        // pre-Phase-2 indexes when no compression flag is passed.
+        { compress: options.compress });
         // ── Phase 2.5: Versioned-graph snapshot (best-effort) ────────────
         // Phase 4 hook: snapshot the freshly-loaded graph into the
         // content-addressed `.codragraph/graphstore/`. Failures here do NOT
@@ -230,6 +315,8 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             repoPath,
             lastCommit: currentCommit,
             indexedAt: new Date().toISOString(),
+            schemaVersion: INDEX_SCHEMA_VERSION,
+            compress: options.compress ?? 'none',
             // 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

package/dist/core/search/bm25-index.js

@@ -10,19 +10,65 @@
  * small repos / CI runners) at the cost of paying that overhead on the
  * first `query`/`context` call in a session.
  */
-import { queryFTS, ensureFTSIndex } from '../lbug/lbug-adapter.js';
+import { queryFTS, ensureFTSIndex, executeQuery as executeCoreQuery, } from '../lbug/lbug-adapter.js';
 /**
- * FTS schema served by `searchFTSFromLbug`. Centralised so that both the
- * CLI/pipeline path and the MCP pool path use identical (table, index,
- * properties) tuples and the lazy-create logic stays in one place.
+ * FTS table set served by `searchFTSFromLbug`. Centralised so that both
+ * the CLI/pipeline path and the MCP pool path stay in lockstep.
+ *
+ * The properties list is computed at FTS-create time via `ftsPropertiesFor`
+ * — for repos that were analysed with `--compress brotli|zstd`, the
+ * `content` column holds base64-of-encoded-bytes and would tokenise to
+ * useless tokens. Those repos get name-only FTS so search at least
+ * matches function/class names instead of returning random hits on
+ * base64 alphabet. Plain (compress='none' / unset) repos get the full
+ * `name + content` index for body-text matches. RFC 0001 Phase 2.5.
  */
-const FTS_INDEXES = [
-    { table: 'File', indexName: 'file_fts', properties: ['name', 'content'] },
-    { table: 'Function', indexName: 'function_fts', properties: ['name', 'content'] },
-    { table: 'Class', indexName: 'class_fts', properties: ['name', 'content'] },
-    { table: 'Method', indexName: 'method_fts', properties: ['name', 'content'] },
-    { table: 'Interface', indexName: 'interface_fts', properties: ['name', 'content'] },
+const FTS_TABLES = [
+    { table: 'File', indexName: 'file_fts' },
+    { table: 'Function', indexName: 'function_fts' },
+    { table: 'Class', indexName: 'class_fts' },
+    { table: 'Method', indexName: 'method_fts' },
+    { table: 'Interface', indexName: 'interface_fts' },
 ];
+const ftsPropertiesFor = (compress) => !compress || compress === 'none' ? ['name', 'content'] : ['name'];
+/**
+ * Look up `meta.compress` for a repo. The MCP path passes `repoId`
+ * (registry-derived); the CLI path passes nothing and we walk up from
+ * cwd. Returns `'none'` whenever the lookup fails so the safe default
+ * (full FTS index) is used — the failure mode is reduced search
+ * quality, never wrong results.
+ */
+async function getCompressMode(repoId) {
+    try {
+        const repoMod = await import('../../storage/repo-manager.js');
+        if (repoId) {
+            // MCP path: registry name is the source of truth. The MCP
+            // backend's `repoId` is `entry.name.toLowerCase()` (or `${name}-${hash}`
+            // on collision); match conservatively against both forms.
+            const entries = await repoMod.listRegisteredRepos();
+            for (const entry of entries) {
+                const base = entry.name.toLowerCase();
+                if (base === repoId || repoId.startsWith(`${base}-`)) {
+                    const meta = await repoMod.loadMeta(entry.storagePath);
+                    return meta?.compress ?? 'none';
+                }
+            }
+            return 'none';
+        }
+        const repo = await repoMod.findRepo(process.cwd());
+        return repo?.meta?.compress ?? 'none';
+    }
+    catch {
+        return 'none';
+    }
+}
+const FALLBACK_SCAN_LIMIT = 50_000;
+const BOOLEAN_QUERY_TOKENS = new Set(['and', 'or', 'not']);
+const FALLBACK_FIELD_WEIGHTS = {
+    name: 4,
+    content: 2,
+    description: 1,
+};
 /**
  * Per-process cache for the MCP pool path: tracks which `(repoId, table)`
  * pairs have been ensured. The CLI/pipeline path gets its own cache inside
@@ -122,6 +168,72 @@ async function queryFTSViaExecutor(executor, tableName, indexName, query, limit)
         return [];
     }
 }
+function searchTerms(query) {
+    const terms = query
+        .toLowerCase()
+        .match(/[\p{L}\p{N}_]+/gu)
+        ?.filter((term) => term.length > 1 && !BOOLEAN_QUERY_TOKENS.has(term));
+    return [...new Set(terms ?? [])];
+}
+function scoreFallbackNode(node, query, properties) {
+    const terms = searchTerms(query);
+    if (terms.length === 0)
+        return 0;
+    const phrase = query.trim().toLowerCase();
+    let score = 0;
+    for (const property of properties) {
+        const raw = node[property];
+        if (raw === null || raw === undefined)
+            continue;
+        const value = String(raw).toLowerCase();
+        if (!value)
+            continue;
+        const weight = FALLBACK_FIELD_WEIGHTS[property] ?? 1;
+        if (phrase.length > 1 && value.includes(phrase)) {
+            score += weight * (terms.length + 1);
+        }
+        for (const term of terms) {
+            if (value.includes(term))
+                score += weight;
+        }
+    }
+    return score;
+}
+async function queryFallbackViaExecutor(executor, tableName, properties, query, limit) {
+    try {
+        const rows = await executor(`
+      MATCH (node:${tableName})
+      RETURN node
+      LIMIT ${FALLBACK_SCAN_LIMIT}
+    `);
+        return rows
+            .map((row) => {
+            const node = row.node || row[0] || {};
+            return {
+                filePath: node.filePath || '',
+                score: scoreFallbackNode(node, query, properties),
+                nodeId: node.nodeId || node.id || '',
+            };
+        })
+            .filter((result) => result.filePath && result.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+    }
+    catch {
+        return [];
+    }
+}
+async function fallbackSearchAllTables(executor, query, limit, 
+// Same compress-aware property selection as the FTS path. Default keeps
+// pre-Phase-2 behaviour (`['name', 'content']`) for callers that don't
+// pass a value.
+properties = ['name', 'content']) {
+    const results = [];
+    for (const { table } of FTS_TABLES) {
+        results.push(await queryFallbackViaExecutor(executor, table, properties, query, limit));
+    }
+    return results;
+}
 /**
  * Search using LadybugDB's built-in FTS (always fresh, reads from disk)
  *
@@ -134,6 +246,8 @@ async function queryFTSViaExecutor(executor, tableName, indexName, query, limit)
  * @returns Ranked search results from FTS indexes
  */
 export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
+    if (!query.trim() || limit <= 0)
+        return [];
     let fileResults, functionResults, classResults, methodResults, interfaceResults;
     if (repoId) {
         // Use MCP connection pool via dynamic import
@@ -149,7 +263,12 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
         const executor = (cypher) => executeQuery(repoId, cypher);
         // Lazy-create FTS indexes on first query for this repo (analyze no longer
         // creates them up-front, so we ensure them here). Cached per-process.
-        for (const { table, indexName, properties } of FTS_INDEXES) {
+        // RFC 0001 Phase 2.5: drop `content` from FTS properties for repos
+        // analysed with --compress brotli|zstd — the column holds encoded
+        // bytes and would tokenise to garbage.
+        const compress = await getCompressMode(repoId);
+        const properties = ftsPropertiesFor(compress);
+        for (const { table, indexName } of FTS_TABLES) {
             await ensureFTSIndexViaExecutor(executor, repoId, table, indexName, properties);
         }
         fileResults = await queryFTSViaExecutor(executor, 'File', 'file_fts', query, limit);
@@ -157,11 +276,24 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
         classResults = await queryFTSViaExecutor(executor, 'Class', 'class_fts', query, limit);
         methodResults = await queryFTSViaExecutor(executor, 'Method', 'method_fts', query, limit);
         interfaceResults = await queryFTSViaExecutor(executor, 'Interface', 'interface_fts', query, limit);
+        if (fileResults.length +
+            functionResults.length +
+            classResults.length +
+            methodResults.length +
+            interfaceResults.length ===
+            0) {
+            [fileResults, functionResults, classResults, methodResults, interfaceResults] =
+                await fallbackSearchAllTables(executor, query, limit, properties);
+        }
     }
     else {
         // Use core lbug adapter (CLI / pipeline context) — also sequential for safety.
         // Lazy-create FTS indexes on first query (analyze no longer does it).
-        for (const { table, indexName, properties } of FTS_INDEXES) {
+        // RFC 0001 Phase 2.5 — same `compress`-aware property selection as the MCP
+        // path; the CLI walks up from cwd to find the repo's meta.json.
+        const compress = await getCompressMode();
+        const properties = ftsPropertiesFor(compress);
+        for (const { table, indexName } of FTS_TABLES) {
             await ensureFTSIndex(table, indexName, [...properties]).catch(() => { });
         }
         fileResults = await queryFTS('File', 'file_fts', query, limit, false).catch(() => []);
@@ -169,6 +301,15 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
         classResults = await queryFTS('Class', 'class_fts', query, limit, false).catch(() => []);
         methodResults = await queryFTS('Method', 'method_fts', query, limit, false).catch(() => []);
         interfaceResults = await queryFTS('Interface', 'interface_fts', query, limit, false).catch(() => []);
+        if (fileResults.length +
+            functionResults.length +
+            classResults.length +
+            methodResults.length +
+            interfaceResults.length ===
+            0) {
+            [fileResults, functionResults, classResults, methodResults, interfaceResults] =
+                await fallbackSearchAllTables(executeCoreQuery, query, limit, properties);
+        }
     }
     // Collect all node scores per filePath to track which nodes actually matched
     const fileNodeScores = new Map();

package/dist/core/wiki/generator.js

@@ -221,7 +221,7 @@ export class WikiGenerator {
                 reportProgress(node.name);
                 return 1;
             }
-            catch (err) {
+            catch (_err) {
                 this.failedModules.push(node.name);
                 reportProgress(`Failed: ${node.name}`);
                 return 0;
@@ -239,7 +239,7 @@ export class WikiGenerator {
                 pagesGenerated++;
                 reportProgress(node.name);
             }
-            catch (err) {
+            catch (_err) {
                 this.failedModules.push(node.name);
                 reportProgress(`Failed: ${node.name}`);
             }
@@ -607,7 +607,7 @@ export class WikiGenerator {
                 this.onProgress('incremental', percent, `${incProcessed}/${affectedNodes.length} — ${node.name}`);
                 return 1;
             }
-            catch (err) {
+            catch (_err) {
                 this.failedModules.push(node.name);
                 incProcessed++;
                 return 0;
@@ -807,7 +807,7 @@ export class WikiGenerator {
         let activeConcurrency = this.concurrency;
         let running = 0;
         let idx = 0;
-        return new Promise((resolve, reject) => {
+        return new Promise((resolve, _reject) => {
             const next = () => {
                 while (running < activeConcurrency && idx < items.length) {
                     const item = items[idx++];

package/dist/mcp/local/local-backend.js

@@ -19,6 +19,7 @@ import { GroupService } from '../../core/group/service.js';
 import { resolveAtGroupMemberRepoPath } from '../../core/group/resolve-at-member.js';
 import { collectBestChunks } from '../../core/embeddings/types.js';
 import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME } from '../../core/lbug/schema.js';
+import { decodeContentField } from '../../core/lbug/content-read.js';
 import { PhaseTimer } from '../../core/search/phase-timer.js';
 import { checkStaleness, checkCwdMatch } from '../../core/git-staleness.js';
 // AI context generation is CLI-only (codragraph analyze)
@@ -835,10 +836,12 @@ export class LocalBackend {
                 try {
                     const contentRows = await executeParameterized(repo.id, `
             MATCH (n {id: $nodeId})
-            RETURN n.content AS content
+            RETURN n.content AS content, n.contentEncoding AS contentEncoding
           `, { nodeId: sym.nodeId });
                     if (contentRows.length > 0) {
-                        content = contentRows[0].content ?? contentRows[0][0];
+                        const raw = contentRows[0].content ?? contentRows[0][0];
+                        const enc = contentRows[0].contentEncoding ?? contentRows[0][1];
+                        content = decodeContentField(raw, enc);
                     }
                 }
                 catch (e) {
@@ -1330,7 +1333,13 @@ export class LocalBackend {
      */
     async resolveSymbolCandidates(repo, query, hints) {
         const { uid, name, include_content } = query;
-        const selectClause = `n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine${include_content ? ', n.content AS content' : ''}`;
+        // RFC 0001 Phase 2: when fetching content, also fetch the per-row
+        // encoding tag so `decodeContentField` can pass it through unchanged
+        // (default 'none') or run brotli/zstd decode. Adding contentEncoding
+        // to the SELECT shifts the numeric-index fallback for content from
+        // r[6] to (still) r[6] — encoding lands at r[7] — but we read by name
+        // first which is the documented preferred path on LadybugDB.
+        const selectClause = `n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine${include_content ? ', n.content AS content, n.contentEncoding AS contentEncoding' : ''}`;
         // Direct UID — zero-ambiguity path.
         if (uid) {
             const rows = await executeParameterized(repo.id, `MATCH (n {id: $uid}) RETURN ${selectClause} LIMIT 1`, { uid });
@@ -1344,7 +1353,11 @@ export class LocalBackend {
                 filePath: (r.filePath ?? r[3]),
                 startLine: (r.startLine ?? r[4]),
                 endLine: (r.endLine ?? r[5]),
-                ...(include_content ? { content: (r.content ?? r[6]) } : {}),
+                ...(include_content
+                    ? {
+                        content: decodeContentField(r.content ?? r[6], r.contentEncoding ?? r[7]),
+                    }
+                    : {}),
             };
             // Same LadybugDB label-enrichment as the name-based path: a UID
             // pointing at a Class must still surface `type: 'Class'` so impact's
@@ -1380,7 +1393,11 @@ export class LocalBackend {
             filePath: (r.filePath ?? r[3]),
             startLine: (r.startLine ?? r[4]),
             endLine: (r.endLine ?? r[5]),
-            ...(include_content ? { content: (r.content ?? r[6]) } : {}),
+            ...(include_content
+                ? {
+                    content: decodeContentField(r.content ?? r[6], r.contentEncoding ?? r[7]),
+                }
+                : {}),
         }));
         // Enrich labels for any candidates where `labels(n)[0]` came back empty.
         // LadybugDB returns an empty string for that projection on certain node

package/dist/mcp/resources.js

@@ -318,7 +318,7 @@ async function getContextResource(backend, repoName) {
     lines.push('  - cypher: Raw graph queries');
     lines.push('  - list_repos: Discover all indexed repositories');
     lines.push('');
-    lines.push('re_index: Run `npx codragraph analyze` in terminal if data is stale');
+    lines.push('re_index: Run `npx @codragraph/cli analyze` in terminal if data is stale');
     lines.push('');
     lines.push('resources_available:');
     lines.push('  - codragraph://repos: All indexed repositories');
@@ -520,7 +520,7 @@ async function getProcessDetailResource(name, backend, repoName) {
 async function getSetupResource(backend) {
     const repos = await backend.listRepos();
     if (repos.length === 0) {
-        return '# CodraGraph\n\nNo repositories indexed. Run: `npx codragraph analyze` in a repository.';
+        return '# CodraGraph\n\nNo repositories indexed. Run: `npx @codragraph/cli analyze` in a repository.';
     }
     const sections = [];
     for (const repo of repos) {
@@ -625,7 +625,6 @@ async function getRecipesResource(backend, repoName, taskFamily) {
     let result;
     try {
         const harnessModuleId = '@codragraph/harness/mcp/handler';
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const mod = (await import(/* @vite-ignore */ harnessModuleId));
         result = await mod.handleHarnessRecipesList({
             task_family: taskFamily,

package/dist/server/api.js

@@ -15,6 +15,7 @@ import { createRequire } from 'node:module';
 import { loadMeta, listRegisteredRepos, getStoragePath } from '../storage/repo-manager.js';
 import { executeQuery, executePrepared, executeWithReusedStatement, streamQuery, closeLbug, withLbugDb, } from '../core/lbug/lbug-adapter.js';
 import { isWriteQuery } from '../core/lbug/pool-adapter.js';
+import { decodeContentField } from '../core/lbug/content-read.js';
 import { NODE_TABLES } from '../_shared/index.js';
 import { searchFTSFromLbug } from '../core/search/bm25-index.js';
 import { hybridSearch } from '../core/search/hybrid-search.js';
@@ -189,7 +190,7 @@ const getNodeQuery = (table, includeContent) => {
     const tableLabel = quoteNodeTable(table);
     if (table === 'File') {
         return includeContent
-            ? `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.content AS content`
+            ? `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.content AS content, n.contentEncoding AS contentEncoding`
             : `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath`;
     }
     if (table === 'Folder') {
@@ -208,7 +209,7 @@ const getNodeQuery = (table, includeContent) => {
         return `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.description AS description`;
     }
     return includeContent
-        ? `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine, n.content AS content`
+        ? `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine, n.content AS content, n.contentEncoding AS contentEncoding`
         : `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine`;
 };
 const mapGraphNodeRow = (table, row, includeContent) => ({
@@ -219,7 +220,7 @@ const mapGraphNodeRow = (table, row, includeContent) => ({
         filePath: row.filePath ?? row[2],
         startLine: row.startLine,
         endLine: row.endLine,
-        content: includeContent ? row.content : undefined,
+        content: includeContent ? decodeContentField(row.content, row.contentEncoding) : undefined,
         responseKeys: row.responseKeys,
         errorKeys: row.errorKeys,
         middleware: row.middleware,

package/dist/storage/repo-manager.d.ts

@@ -36,10 +36,49 @@
  * so the registry stabilises over analyze/re-analyze cycles.
  */
 export declare const canonicalizePath: (p: string) => string;
+/**
+ * On-disk schema version for `.codragraph/lbug` and `.codragraph/meta.json`.
+ *
+ *   1  — pre-RFC-0001-Phase-2 layout. Node tables have `content STRING`
+ *        but no `contentEncoding` column. Implicit/missing on existing
+ *        1.6.x and 1.7.x indexes (RepoMeta.schemaVersion was undefined).
+ *   2  — RFC 0001 Phase 2: every node table that has `content` also has
+ *        a `contentEncoding STRING DEFAULT 'none'` column. Writers may
+ *        opt into compression via `--compress brotli|zstd` (compression
+ *        is OFF by default, so existing readers keep working). Readers
+ *        decode based on the per-row encoding tag.
+ *
+ * Bumping this is the migration trigger: `runFullAnalysis` forces a
+ * full re-analyze when an existing index has a missing or older
+ * `schemaVersion` field, because adding a column to an existing
+ * LadybugDB table via ALTER is not validated end-to-end yet — fresh
+ * `CREATE NODE TABLE` is the supported path.
+ */
+export declare const INDEX_SCHEMA_VERSION: 2;
 export interface RepoMeta {
     repoPath: string;
     lastCommit: string;
     indexedAt: string;
+    /**
+     * On-disk schema version (see {@link INDEX_SCHEMA_VERSION}). Absent on
+     * indexes written by 1.7.x or earlier; `runFullAnalysis` treats those
+     * as needing a full re-analyze when they're loaded by a 1.8+ CLI.
+     */
+    schemaVersion?: number;
+    /**
+     * RFC 0001 Phase 2 — the per-row content encoding chosen at the last
+     * `analyze --compress` invocation. `'none'` (or absent) means rows
+     * carry plain text; `'brotli'` / `'zstd'` means rows are compressed
+     * and consumers must decode. Persisted so query-time tooling can
+     * detect the compressed mode without sampling rows.
+     *
+     * Phase 2.5 hooks: `core/search/bm25-index.ts` reads this field at
+     * FTS-create time and drops `content` from the FTS property list
+     * when set to a non-`'none'` value (full-text search falls back to
+     * symbol-name matches). Embeddings and graph queries are unaffected
+     * — they decode at the read boundary.
+     */
+    compress?: 'none' | 'brotli' | 'zstd';
     /**
      * Canonical `origin` remote URL captured at index time. Used to
      * fingerprint the same logical repo across multiple on-disk clones

package/dist/storage/repo-manager.js

@@ -49,6 +49,25 @@ export const canonicalizePath = (p) => {
         return resolved;
     }
 };
+/**
+ * On-disk schema version for `.codragraph/lbug` and `.codragraph/meta.json`.
+ *
+ *   1  — pre-RFC-0001-Phase-2 layout. Node tables have `content STRING`
+ *        but no `contentEncoding` column. Implicit/missing on existing
+ *        1.6.x and 1.7.x indexes (RepoMeta.schemaVersion was undefined).
+ *   2  — RFC 0001 Phase 2: every node table that has `content` also has
+ *        a `contentEncoding STRING DEFAULT 'none'` column. Writers may
+ *        opt into compression via `--compress brotli|zstd` (compression
+ *        is OFF by default, so existing readers keep working). Readers
+ *        decode based on the per-row encoding tag.
+ *
+ * Bumping this is the migration trigger: `runFullAnalysis` forces a
+ * full re-analyze when an existing index has a missing or older
+ * `schemaVersion` field, because adding a column to an existing
+ * LadybugDB table via ALTER is not validated end-to-end yet — fresh
+ * `CREATE NODE TABLE` is the supported path.
+ */
+export const INDEX_SCHEMA_VERSION = 2;
 const CODRAGRAPH_DIR = '.codragraph';
 // ─── Local Storage Helpers ─────────────────────────────────────────────
 /**