@codragraph/cli 1.6.4 → 2.1.0

package/dist/core/graphstore/cgdb-row-source.js

@@ -0,0 +1,141 @@
+/**
+ * Adapter exposing a live LadybugDB instance as a `@codragraph/graphstore`
+ * `RowSource`. Used by the analyze pipeline (Phase 4) to snapshot the
+ * loaded graph into the content-addressed store.
+ *
+ * Best-effort by design: any table that errors at query time is skipped
+ * (with the failure surfaced through the optional `onSkip` callback) so
+ * the surrounding analyze flow never breaks because the versioning hook
+ * misbehaves.
+ */
+import { NODE_TABLES, REL_TABLE_NAME } from '../../_shared/index.js';
+import { executeQuery } from '../cgdb/cgdb-adapter.js';
+export const createCgdbRowSource = (opts = {}) => {
+    const onSkip = opts.onSkip ?? (() => { });
+    const tables = opts.nodeTables ?? NODE_TABLES;
+    const listNodeTables = async () => {
+        return [...tables];
+    };
+    const streamNodeTable = async function* (tableName) {
+        let rows;
+        try {
+            // `MATCH (n:T) RETURN n` returns one row per node. The node value
+            // is reachable as either `row.n` (named-column form) or `row[0]`
+            // (positional form) depending on the LadybugDB result-shape mode;
+            // we accept both, mirroring the resilient pattern used by
+            // `core/search/bm25-index.ts` for FTS results. Tables that do not
+            // exist on disk for a given repo throw here — we treat that as
+            // "no rows" via the onSkip callback rather than a hard failure.
+            rows = await executeQuery(`MATCH (n:${tableName}) RETURN n`);
+        }
+        catch (err) {
+            onSkip(tableName, err);
+            return;
+        }
+        let yielded = 0;
+        for (const raw of rows) {
+            const node = unwrapNode(raw);
+            if (!node)
+                continue;
+            yield normalizeNodeRow(node);
+            yielded++;
+        }
+        // If the query reported rows but none unwrapped, surface that as a
+        // skip so the analyze log makes the silent-empty failure mode
+        // visible instead of producing a 0-row snapshot for the table.
+        if (rows.length > 0 && yielded === 0) {
+            onSkip(tableName, new Error(`cgdb-row-source: query returned ${rows.length} row(s) for "${tableName}" but none had an unwrappable node — ` +
+                `result shape changed? expected row.n or row[0] to be the node`));
+        }
+    };
+    const streamEdges = async function* () {
+        let rows;
+        try {
+            // Project `from`/`to`/`type` as scalar columns and the full rel as
+            // `rel`. Scalars give us a deterministic edge id even if the rel
+            // payload's shape changes; `rel` carries any extra properties for
+            // hashing.
+            rows = await executeQuery(`MATCH (a)-[r:${REL_TABLE_NAME}]->(b) RETURN a.id AS \`from\`, b.id AS \`to\`, r.type AS type, r AS rel`);
+        }
+        catch (err) {
+            onSkip(REL_TABLE_NAME, err);
+            return;
+        }
+        let yielded = 0;
+        for (const raw of rows) {
+            const r = raw;
+            const from = pickField(r, 'from', 0);
+            const to = pickField(r, 'to', 1);
+            const type = pickField(r, 'type', 2);
+            const rel = pickField(r, 'rel', 3);
+            if (typeof from !== 'string' || typeof to !== 'string')
+                continue;
+            yield normalizeEdgeRow({ from, to, type, rel: isPlainObject(rel) ? rel : null });
+            yielded++;
+        }
+        if (rows.length > 0 && yielded === 0) {
+            onSkip(REL_TABLE_NAME, new Error(`cgdb-row-source: edges query returned ${rows.length} row(s) but none had a string from/to — ` +
+                `result shape changed?`));
+        }
+    };
+    return { listNodeTables, streamNodeTable, streamEdges };
+};
+/**
+ * Pull the node out of an executeQuery result row, accepting either the
+ * named-column form (`row.n`) or the positional form (`row[0]`). Returns
+ * null when the row is missing or the node value isn't an object — the
+ * caller treats that as "skip and surface".
+ */
+const unwrapNode = (raw) => {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    const candidate = r['n'] ?? r[0];
+    return isPlainObject(candidate) ? candidate : null;
+};
+/** Read a field from an executeQuery row, falling back to the positional index. */
+const pickField = (row, named, positional) => {
+    if (!row)
+        return undefined;
+    return row[named] ?? row[positional];
+};
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/**
+ * Sanitize a node row for canonical hashing:
+ *   - Drop LadybugDB-specific internal fields (`_id`, `_label`) that are
+ *     not content-bearing — including them would make the hash sensitive
+ *     to internal storage offsets and break dedup across snapshots.
+ *   - Sort keys deterministically (canonical JSON in the serializer
+ *     already does this, but doing it once here keeps the row payload
+ *     stable when we ever swap engines).
+ */
+const normalizeNodeRow = (node) => {
+    const out = {};
+    for (const key of Object.keys(node).sort()) {
+        if (key === '_id' || key === '_label')
+            continue;
+        out[key] = node[key];
+    }
+    return out;
+};
+const normalizeEdgeRow = (r) => {
+    const props = {};
+    if (r.rel && typeof r.rel === 'object') {
+        for (const key of Object.keys(r.rel).sort()) {
+            // Skip the synthetic from/to/type that show up under `rel` too —
+            // we already project them as top-level columns and don't want
+            // duplication in the canonical row.
+            if (key === 'from' || key === 'to' || key === 'type')
+                continue;
+            if (key.startsWith('_'))
+                continue;
+            props[key] = r.rel[key];
+        }
+    }
+    return {
+        from: String(r.from),
+        to: String(r.to),
+        type: typeof r.type === 'string' ? r.type : String(r.type ?? ''),
+        ...props,
+    };
+};

package/dist/core/graphstore/index.d.ts

@@ -38,7 +38,7 @@ export interface RecordAnalysisSnapshotResult {
 /**
  * Snapshot the currently-loaded LadybugDB into the content-addressed
  * store and advance the active branch's HEAD to the new commit. Caller
- * is expected to have already initialized lbug with `initLbug(...)`.
+ * is expected to have already initialized cgdb with `initCgdb(...)`.
  *
  * Returns null if anything goes sideways (logged via `onSkipTable`); the
  * analyze pipeline treats that as "no snapshot for this run".

package/dist/core/graphstore/index.js

@@ -9,13 +9,13 @@
  */
 import path from 'node:path';
 import { FsCAS, serializeSnapshot, createCommit, setHead, writeHeadBranch, resolveHeadCommit, DEFAULT_BRANCH, } from '@codragraph/graphstore';
-import { createLbugRowSource } from './lbug-row-source.js';
+import { createCgdbRowSource } from './cgdb-row-source.js';
 /** Subdirectory of `<repo>/.codragraph` that holds versioning artifacts. */
 export const GRAPHSTORE_SUBDIR = 'graphstore';
 /**
  * Snapshot the currently-loaded LadybugDB into the content-addressed
  * store and advance the active branch's HEAD to the new commit. Caller
- * is expected to have already initialized lbug with `initLbug(...)`.
+ * is expected to have already initialized cgdb with `initCgdb(...)`.
  *
  * Returns null if anything goes sideways (logged via `onSkipTable`); the
  * analyze pipeline treats that as "no snapshot for this run".
@@ -26,7 +26,7 @@ export const recordAnalysisSnapshot = async (opts) => {
     let serialized;
     try {
         serialized = await serializeSnapshot({
-            source: createLbugRowSource({ onSkip: opts.onSkipTable }),
+            source: createCgdbRowSource({ onSkip: opts.onSkipTable }),
             cas,
             indexedRepoCommit: opts.indexedRepoCommit,
         });

package/dist/core/group/bridge-db.d.ts

@@ -1,4 +1,4 @@
-import type { LbugValue } from '@ladybugdb/core';
+import type { LbugValue as CgdbValue } from '@ladybugdb/core';
 import type { BridgeHandle, BridgeMeta, StoredContract, CrossLink, RepoSnapshot } from './types.js';
 export declare function contractNodeId(repo: string, contractId: string, role: string, filePath: string): string;
 /**
@@ -46,7 +46,7 @@ export declare function indexContract(index: ContractLookupIndex, contract: Stor
 export declare function findContractNode(index: ContractLookupIndex, repo: string, role: 'consumer' | 'provider', symbolUid: string, filePath: string, symbolName: string): string | null;
 export declare function openBridgeDb(dbPath: string): Promise<BridgeHandle>;
 export declare function ensureBridgeSchema(handle: BridgeHandle): Promise<void>;
-export declare function queryBridge<T>(handle: BridgeHandle, cypher: string, params?: Record<string, LbugValue>): Promise<T[]>;
+export declare function queryBridge<T>(handle: BridgeHandle, cypher: string, params?: Record<string, CgdbValue>): Promise<T[]>;
 export declare function closeBridgeDb(handle: BridgeHandle): Promise<void>;
 export declare function retryRename(src: string, dst: string, attempts?: number): Promise<void>;
 export declare function writeBridgeMeta(groupDir: string, meta: BridgeMeta): Promise<void>;

package/dist/core/group/bridge-db.js

@@ -1,7 +1,7 @@
 import fsp from 'node:fs/promises';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
-import lbug from '@ladybugdb/core';
+import cgdb from '@ladybugdb/core';
 import { BRIDGE_SCHEMA_QUERIES, BRIDGE_SCHEMA_VERSION } from './bridge-schema.js';
 import { dedupeContracts, dedupeCrossLinks } from './normalization.js';
 export function contractNodeId(repo, contractId, role, filePath) {
@@ -74,8 +74,8 @@ export function findContractNode(index, repo, role, symbolUid, filePath, symbolN
 export async function openBridgeDb(dbPath) {
     const parentDir = path.dirname(dbPath);
     await fsp.mkdir(parentDir, { recursive: true });
-    const db = new lbug.Database(dbPath, 0, false, false); // writable
-    const conn = new lbug.Connection(db);
+    const db = new cgdb.Database(dbPath, 0, false, false); // writable
+    const conn = new cgdb.Connection(db);
     return { _db: db, _conn: conn, groupDir: parentDir };
 }
 /**
@@ -83,10 +83,10 @@ export async function openBridgeDb(dbPath) {
  * CREATE NODE TABLE or CREATE REL TABLE statement hits an already-existing
  * table. LadybugDB DDL doesn't support IF NOT EXISTS, and its JS driver
  * doesn't expose typed error codes, so we match on the message substring —
- * the same pattern used by `core/lbug/lbug-adapter.ts`. If a future
+ * the same pattern used by `core/cgdb/cgdb-adapter.ts`. If a future
  * LadybugDB release changes the wording, update this constant.
  */
-const LBUG_ALREADY_EXISTS_MSG = 'already exists';
+const CGDB_ALREADY_EXISTS_MSG = 'already exists';
 export async function ensureBridgeSchema(handle) {
     const conn = handle._conn;
     for (const q of BRIDGE_SCHEMA_QUERIES) {
@@ -95,26 +95,98 @@ export async function ensureBridgeSchema(handle) {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            if (!msg.includes(LBUG_ALREADY_EXISTS_MSG))
+            if (!msg.includes(CGDB_ALREADY_EXISTS_MSG))
                 throw err;
         }
     }
 }
-export async function queryBridge(handle, cypher, params) {
+/**
+ * Close every QueryResult / PreparedStatement before letting V8 GC them.
+ * Same close-order discipline as `core/cgdb/cgdb-adapter.ts:closeQueryResult`
+ * — leaking these handles past `conn.close()` corrupts LadybugDB's native
+ * file lock on Windows ("Error 33: The process cannot access the file
+ * because it is being used by another process") and segfaults on
+ * process exit elsewhere. Best-effort: wrap close calls in try/catch so
+ * a finalizer that already ran doesn't poison the queryBridge return.
+ */
+async function closeBridgeHandle(h) {
+    if (!h)
+        return;
+    const candidates = Array.isArray(h) ? h : [h];
+    for (const r of candidates) {
+        try {
+            const close = r?.close;
+            if (typeof close === 'function')
+                await Promise.resolve(close.call(r));
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}
+/**
+ * True iff the error is a Windows-only transient file-lock surfaced by
+ * LadybugDB's native binding immediately after a writer process closes
+ * the same DB file. Symptom is `Error 33` on the read path even though
+ * `db.close()` returned cleanly at the JS layer — the kernel hasn't
+ * fully released the exclusive lock yet. Retrying with backoff is the
+ * documented workaround for this class of Windows-fs interactions.
+ */
+function isTransientCgdbLockError(err) {
+    const msg = err?.message ?? '';
+    return (msg.includes('Error 33') ||
+        msg.includes('locked a portion of the file') ||
+        msg.includes('cannot access the file because it is being used by another process'));
+}
+async function queryBridgeOnce(handle, cypher, params) {
     const conn = handle._conn;
     if (params && Object.keys(params).length > 0) {
         const stmt = await conn.prepare(cypher);
         if (!stmt.isSuccess()) {
             const errMsg = await stmt.getErrorMessage();
+            await closeBridgeHandle(stmt);
             throw new Error(`Bridge query prepare failed: ${errMsg}`);
         }
         const queryResult = await conn.execute(stmt, params);
         const result = unwrapQueryResult(queryResult);
-        return (await result.getAll());
+        try {
+            return (await result.getAll());
+        }
+        finally {
+            await closeBridgeHandle(queryResult);
+            await closeBridgeHandle(stmt);
+        }
     }
     const queryResult = await conn.query(cypher);
     const result = unwrapQueryResult(queryResult);
-    return (await result.getAll());
+    try {
+        return (await result.getAll());
+    }
+    finally {
+        await closeBridgeHandle(queryResult);
+    }
+}
+export async function queryBridge(handle, cypher, params) {
+    // Retry on Windows-transient file-lock errors. Reads issued through a
+    // freshly-opened readonly Database can race the writer's
+    // post-`db.close()` lock release on Windows + Node 22.14 (LadybugDB
+    // native binding holds the kernel lock briefly after the JS-level
+    // close returns). Backoff doubles per attempt up to ~3 s total — well
+    // below any user-visible CLI delay budget but enough to absorb a slow
+    // Windows kernel lock release.
+    const ATTEMPTS = 7;
+    for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+        try {
+            return await queryBridgeOnce(handle, cypher, params);
+        }
+        catch (err) {
+            if (!isTransientCgdbLockError(err) || attempt === ATTEMPTS - 1)
+                throw err;
+            await new Promise((r) => setTimeout(r, 50 * Math.pow(2, attempt)));
+        }
+    }
+    // Unreachable: the loop either returns or throws on the last attempt.
+    throw new Error('queryBridge: retry loop exited unexpectedly');
 }
 /**
  * LadybugDB's `conn.query` / `conn.execute` can return either a single
@@ -176,7 +248,7 @@ export async function writeBridgeMeta(groupDir, meta) {
     // Use retryRename for consistency with writeBridge's atomic swap — on
     // Windows a concurrent reader can cause EBUSY/EPERM even on a tiny
     // meta.json, and we don't want meta write to be less robust than the
-    // bridge.lbug swap it accompanies.
+    // bridge.cgdb swap it accompanies.
     await retryRename(tmp, target);
 }
 export async function readBridgeMeta(groupDir) {
@@ -203,9 +275,9 @@ export async function writeBridge(groupDir, input) {
     await fsp.mkdir(groupDir, { recursive: true });
     const contracts = dedupeContracts(input.contracts);
     const crossLinks = dedupeCrossLinks(input.crossLinks);
-    const finalPath = path.join(groupDir, 'bridge.lbug');
-    const tmpPath = path.join(groupDir, 'bridge.lbug.tmp');
-    const bakPath = path.join(groupDir, 'bridge.lbug.bak');
+    const finalPath = path.join(groupDir, 'bridge.cgdb');
+    const tmpPath = path.join(groupDir, 'bridge.cgdb.tmp');
+    const bakPath = path.join(groupDir, 'bridge.cgdb.bak');
     const report = {
         contractsInserted: 0,
         contractsFailed: 0,
@@ -394,7 +466,7 @@ export async function writeBridge(groupDir, input) {
 /*  openBridgeDbReadOnly                                               */
 /* ------------------------------------------------------------------ */
 export async function openBridgeDbReadOnly(groupDir) {
-    const dbPath = path.join(groupDir, 'bridge.lbug');
+    const dbPath = path.join(groupDir, 'bridge.cgdb');
     try {
         await fsp.access(dbPath);
     }
@@ -404,7 +476,7 @@ export async function openBridgeDbReadOnly(groupDir) {
         // triggers bak recovery is an interrupted writer, which on Windows may
         // still be holding an open handle on `.bak` for a few milliseconds when
         // a reader races in. EBUSY/EPERM retries recover that case silently.
-        const bakPath = path.join(groupDir, 'bridge.lbug.bak');
+        const bakPath = path.join(groupDir, 'bridge.cgdb.bak');
         try {
             await fsp.access(bakPath);
             await retryRename(bakPath, dbPath);
@@ -421,32 +493,47 @@ export async function openBridgeDbReadOnly(groupDir) {
     // Open the native handle. If Connection construction throws AFTER
     // Database was successfully allocated, we'd leak the native Database
     // object. Wrap each step separately and tear down the partial handle.
-    let db;
-    let conn;
-    try {
-        db = new lbug.Database(dbPath, 0, false, true); // readOnly
-        conn = new lbug.Connection(db);
-        return { _db: db, _conn: conn, groupDir };
-    }
-    catch {
-        if (conn) {
-            try {
-                await conn.close();
-            }
-            catch {
-                /* ignore */
-            }
+    //
+    // Retry on the Windows-transient lock error: the LadybugDB native
+    // binding holds the kernel file lock briefly past `db.close()` on
+    // Windows + Node 22.14, so a reader that races a recent writer can
+    // hit "Error 33: locked a portion of the file" on the constructor's
+    // first 4 KB header read. Backoff up to ~3 s lets the writer's lock
+    // age out — enough headroom for any normal write→read sequence
+    // without becoming a user-visible delay.
+    const ATTEMPTS = 7;
+    for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+        let db;
+        let conn;
+        try {
+            db = new cgdb.Database(dbPath, 0, false, true); // readOnly
+            conn = new cgdb.Connection(db);
+            return { _db: db, _conn: conn, groupDir };
         }
-        if (db) {
-            try {
-                await db.close();
+        catch (err) {
+            if (conn) {
+                try {
+                    await conn.close();
+                }
+                catch {
+                    /* ignore */
+                }
             }
-            catch {
-                /* ignore */
+            if (db) {
+                try {
+                    await db.close();
+                }
+                catch {
+                    /* ignore */
+                }
             }
+            if (!isTransientCgdbLockError(err) || attempt === ATTEMPTS - 1)
+                return null;
+            await new Promise((r) => setTimeout(r, 50 * Math.pow(2, attempt)));
+            continue;
         }
-        return null;
     }
+    return null;
 }
 /* ------------------------------------------------------------------ */
 /*  bridgeExists                                                       */

package/dist/core/group/bridge-schema.d.ts

@@ -1,19 +1,19 @@
 /**
  * Bridge LadybugDB schema for cross-repo Contract Registry.
- * Separate from per-repo schema in lbug/schema.ts.
+ * Separate from per-repo schema in cgdb/schema.ts.
  */
 /**
- * Version of the bridge.lbug schema below. `openBridgeDbReadOnly` compares
+ * Version of the bridge.cgdb schema below. `openBridgeDbReadOnly` compares
  * this against `meta.json`'s version field and returns `null` on mismatch,
  * which trips the caller into either the JSON fallback path or a fresh
- * `group sync` that rebuilds `bridge.lbug` from scratch.
+ * `group sync` that rebuilds `bridge.cgdb` from scratch.
  *
  * Migration contract for contributors bumping this constant:
  *   1. Bump the number (e.g. `1` → `2`).
  *   2. Update the DDL below to match the new schema.
  *   3. DO NOT attempt an online migration in this file — the version gate
  *      is intentionally a "discard and re-sync" strategy for V1. An old
- *      bridge.lbug whose version doesn't match is treated as opaque and
+ *      bridge.cgdb whose version doesn't match is treated as opaque and
  *      rebuilt by the next `group sync`.
  *   4. If online migration becomes necessary (e.g. when groups accumulate
  *      large amounts of embedding data), add a migration path as a

package/dist/core/group/bridge-schema.js

@@ -1,19 +1,19 @@
 /**
  * Bridge LadybugDB schema for cross-repo Contract Registry.
- * Separate from per-repo schema in lbug/schema.ts.
+ * Separate from per-repo schema in cgdb/schema.ts.
  */
 /**
- * Version of the bridge.lbug schema below. `openBridgeDbReadOnly` compares
+ * Version of the bridge.cgdb schema below. `openBridgeDbReadOnly` compares
  * this against `meta.json`'s version field and returns `null` on mismatch,
  * which trips the caller into either the JSON fallback path or a fresh
- * `group sync` that rebuilds `bridge.lbug` from scratch.
+ * `group sync` that rebuilds `bridge.cgdb` from scratch.
  *
  * Migration contract for contributors bumping this constant:
  *   1. Bump the number (e.g. `1` → `2`).
  *   2. Update the DDL below to match the new schema.
  *   3. DO NOT attempt an online migration in this file — the version gate
  *      is intentionally a "discard and re-sync" strategy for V1. An old
- *      bridge.lbug whose version doesn't match is treated as opaque and
+ *      bridge.cgdb whose version doesn't match is treated as opaque and
  *      rebuilt by the next `group sync`.
  *   4. If online migration becomes necessary (e.g. when groups accumulate
  *      large amounts of embedding data), add a migration path as a

package/dist/core/group/cross-impact.js

@@ -199,19 +199,19 @@ async function ensureBridgeReady(groupDir) {
             error: `Bridge schema version mismatch (meta.json has ${meta.version}, expected ${BRIDGE_SCHEMA_VERSION}). Run codragraph group sync for this group.`,
         };
     }
-    const dbPath = path.join(groupDir, 'bridge.lbug');
+    const dbPath = path.join(groupDir, 'bridge.cgdb');
     try {
         await fsp.access(dbPath);
     }
     catch {
         return {
-            error: `No bridge.lbug in this group directory. Run codragraph group sync (schema ${BRIDGE_SCHEMA_VERSION}).`,
+            error: `No bridge.cgdb in this group directory. Run codragraph group sync (schema ${BRIDGE_SCHEMA_VERSION}).`,
         };
     }
     const handle = await openBridgeDbReadOnly(groupDir);
     if (!handle) {
         return {
-            error: `Could not open bridge.lbug read-only (schema ${BRIDGE_SCHEMA_VERSION}). Run codragraph group sync.`,
+            error: `Could not open bridge.cgdb read-only (schema ${BRIDGE_SCHEMA_VERSION}). Run codragraph group sync.`,
         };
     }
     return { handle };

package/dist/core/group/sync.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { Buffer } from 'node:buffer';
-import { initLbug, closeLbug, executeParameterized } from '../lbug/pool-adapter.js';
+import { initCgdb, closeCgdb, executeParameterized } from '../cgdb/pool-adapter.js';
 import { readRegistry } from '../../storage/repo-manager.js';
 import { HttpRouteExtractor } from './extractors/http-route-extractor.js';
 import { GrpcExtractor } from './extractors/grpc-extractor.js';
@@ -78,9 +78,9 @@ export async function syncGroup(config, opts) {
                     continue;
                 }
                 const poolId = handle.id;
-                const lbugPath = path.join(handle.storagePath, 'lbug');
+                const cgdbPath = path.join(handle.storagePath, 'cgdb');
                 try {
-                    await initLbug(poolId, lbugPath);
+                    await initCgdb(poolId, cgdbPath);
                     openPoolIds.push(poolId);
                     const executor = (query, params) => executeParameterized(poolId, query, params ?? {});
                     dbExecutors.set(groupPath, executor);
@@ -139,7 +139,7 @@ export async function syncGroup(config, opts) {
         }
         finally {
             for (const id of [...new Set(openPoolIds)]) {
-                await closeLbug(id).catch(() => { });
+                await closeCgdb(id).catch(() => { });
             }
         }
     }

package/dist/core/lbug/content-read.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Read-side decoder for `content` columns in lbug node rows.
+ *
+ * RFC 0001 Phase 2 introduces an optional `contentEncoding` column on
+ * every node table that has `content`. Default is `'none'` (passthrough)
+ * so existing reads keep working unchanged. When a writer opts into
+ * `--compress brotli|zstd`, the column carries the encoding tag and the
+ * `content` column carries base64-encoded compressed bytes — readers
+ * MUST run those bytes back through `decodeContent` before handing them
+ * to a consumer (MCP tool result, HTTP API response, embedding model,
+ * LLM input).
+ *
+ * Centralizing the decode in one helper has two benefits:
+ *   1. Shim sites are 2-line changes: add `, n.contentEncoding AS
+ *      contentEncoding` to the Cypher RETURN, and pipe the row through
+ *      `decodeContentField` (or `decodeContentRow`) at the boundary.
+ *   2. Anyone hunting for "where does the read path decode compressed
+ *      bytes" greps for `decodeContentField` and gets every site in one
+ *      shot — no per-table feature detection scattered across files.
+ */
+/**
+ * Decode a single (content, contentEncoding) pair from a Cypher row.
+ *
+ * Returns the input content unchanged when:
+ *   - the encoding is missing / empty / `'none'` (the common case for
+ *     1.6.x – 1.7.x indexes, plus any 1.8+ index written without
+ *     `--compress`);
+ *   - content is null/undefined (caller decides whether that's an error);
+ *   - content is not a string (pre-Phase-2 indexes never wrote non-string
+ *     content, but defensive: don't crash a read path on a malformed row).
+ *
+ * Throws (via `decodeContent`) only when the row claims an encoding this
+ * CLI build can't decode — that's a forward-compat error and the right
+ * behavior is to fail loudly rather than return wrong content.
+ */
+export declare function decodeContentField(content: unknown, encoding: unknown): string | undefined;
+/**
+ * Apply `decodeContentField` to a row that carries `content` and
+ * `contentEncoding` keys (or their numeric column-index aliases).
+ *
+ * The numeric-fallback shape (`r[N]`) mirrors LadybugDB's row format —
+ * driver versions vary on whether named keys are populated, so existing
+ * read sites do `r.content ?? r[N]`. This helper accepts the same
+ * pattern. Returns a NEW object (does not mutate input).
+ */
+export declare function decodeContentRow<T extends Record<string, unknown>>(row: T, contentKey?: keyof T, encodingKey?: keyof T): T;

package/dist/core/lbug/content-read.js

@@ -0,0 +1,64 @@
+/**
+ * Read-side decoder for `content` columns in lbug node rows.
+ *
+ * RFC 0001 Phase 2 introduces an optional `contentEncoding` column on
+ * every node table that has `content`. Default is `'none'` (passthrough)
+ * so existing reads keep working unchanged. When a writer opts into
+ * `--compress brotli|zstd`, the column carries the encoding tag and the
+ * `content` column carries base64-encoded compressed bytes — readers
+ * MUST run those bytes back through `decodeContent` before handing them
+ * to a consumer (MCP tool result, HTTP API response, embedding model,
+ * LLM input).
+ *
+ * Centralizing the decode in one helper has two benefits:
+ *   1. Shim sites are 2-line changes: add `, n.contentEncoding AS
+ *      contentEncoding` to the Cypher RETURN, and pipe the row through
+ *      `decodeContentField` (or `decodeContentRow`) at the boundary.
+ *   2. Anyone hunting for "where does the read path decode compressed
+ *      bytes" greps for `decodeContentField` and gets every site in one
+ *      shot — no per-table feature detection scattered across files.
+ */
+import { decodeContent } from '@codragraph/graphstore';
+/**
+ * Decode a single (content, contentEncoding) pair from a Cypher row.
+ *
+ * Returns the input content unchanged when:
+ *   - the encoding is missing / empty / `'none'` (the common case for
+ *     1.6.x – 1.7.x indexes, plus any 1.8+ index written without
+ *     `--compress`);
+ *   - content is null/undefined (caller decides whether that's an error);
+ *   - content is not a string (pre-Phase-2 indexes never wrote non-string
+ *     content, but defensive: don't crash a read path on a malformed row).
+ *
+ * Throws (via `decodeContent`) only when the row claims an encoding this
+ * CLI build can't decode — that's a forward-compat error and the right
+ * behavior is to fail loudly rather than return wrong content.
+ */
+export function decodeContentField(content, encoding) {
+    if (content === undefined || content === null)
+        return undefined;
+    if (typeof content !== 'string')
+        return content;
+    if (typeof encoding !== 'string' || encoding === '' || encoding === 'none') {
+        return content;
+    }
+    return decodeContent(content, encoding);
+}
+/**
+ * Apply `decodeContentField` to a row that carries `content` and
+ * `contentEncoding` keys (or their numeric column-index aliases).
+ *
+ * The numeric-fallback shape (`r[N]`) mirrors LadybugDB's row format —
+ * driver versions vary on whether named keys are populated, so existing
+ * read sites do `r.content ?? r[N]`. This helper accepts the same
+ * pattern. Returns a NEW object (does not mutate input).
+ */
+export function decodeContentRow(row, contentKey = 'content', encodingKey = 'contentEncoding') {
+    const content = row[contentKey];
+    if (content === undefined || content === null)
+        return row;
+    const encoding = row[encodingKey];
+    if (typeof encoding !== 'string' || encoding === '' || encoding === 'none')
+        return row;
+    return { ...row, [contentKey]: decodeContentField(content, encoding) };
+}