@andespindola/brainlink 0.1.0-beta.11 → 0.1.0-beta.111

package/dist/domain/context.js

@@ -1,13 +1,50 @@
+import { middleOutIndices } from './middle-out.js';
+const maxSectionsPerDocument = 3;
+const byScore = (left, right) => right.score - left.score || left.title.localeCompare(right.title);
+const byOrdinal = (left, right) => (left.chunkOrdinal ?? Number.MAX_SAFE_INTEGER) - (right.chunkOrdinal ?? Number.MAX_SAFE_INTEGER);
+const middleOutDocumentResults = (results) => {
+    if (results.length <= 1) {
+        return results;
+    }
+    const sortedByOrdinal = [...results].sort(byOrdinal);
+    const pivotChunkId = [...results].sort(byScore)[0]?.chunkId;
+    const pivotIndex = sortedByOrdinal.findIndex((result) => result.chunkId === pivotChunkId);
+    if (pivotIndex < 0) {
+        return [...results].sort(byScore);
+    }
+    return middleOutIndices(sortedByOrdinal.length, pivotIndex).map((index) => sortedByOrdinal[index]);
+};
 export const selectContextSections = (results, maxTokens) => {
-    const selected = results.reduce((state, result) => {
-        const tokenCost = Math.ceil(result.content.length / 4);
-        if (state.usedTokens + tokenCost > maxTokens || state.seenDocuments.has(result.documentId)) {
-            return state;
+    const grouped = results.reduce((state, result) => {
+        const current = state.get(result.documentId) ?? [];
+        state.set(result.documentId, [...current, result]);
+        return state;
+    }, new Map());
+    const documentOrder = Array.from(results.reduce((state, result) => {
+        if (!state.has(result.documentId)) {
+            state.set(result.documentId, result.score);
         }
-        return {
-            usedTokens: state.usedTokens + tokenCost,
-            sections: [
-                ...state.sections,
+        return state;
+    }, new Map()).entries())
+        .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]))
+        .map(([documentId]) => documentId);
+    const selected = documentOrder.reduce((state, documentId) => {
+        const ordered = middleOutDocumentResults(grouped.get(documentId) ?? []);
+        let usedTokens = state.usedTokens;
+        let sections = state.sections;
+        let seenChunks = state.seenChunks;
+        for (let index = 0; index < ordered.length && index < maxSectionsPerDocument; index += 1) {
+            const result = ordered[index];
+            if (seenChunks.has(result.chunkId)) {
+                continue;
+            }
+            const tokenCost = Math.ceil(result.content.length / 4);
+            if (usedTokens + tokenCost > maxTokens) {
+                break;
+            }
+            usedTokens += tokenCost;
+            sections = [
+                ...sections,
                 {
                     title: result.title,
                     path: result.path,
@@ -16,13 +53,18 @@ export const selectContextSections = (results, maxTokens) => {
                     searchMode: result.searchMode,
                     tags: result.tags
                 }
-            ],
-            seenDocuments: new Set([...state.seenDocuments, result.documentId])
+            ];
+            seenChunks = new Set([...seenChunks, result.chunkId]);
+        }
+        return {
+            usedTokens,
+            sections,
+            seenChunks
         };
     }, {
         usedTokens: 0,
         sections: [],
-        seenDocuments: new Set()
+        seenChunks: new Set()
     });
     return selected.sections;
 };

package/dist/domain/graph-layout.js

@@ -20,6 +20,7 @@ const segmentAngles = {
     Evaluation: 2.08,
     Security: 2.82
 };
+const hubTitlePattern = /\b(memory\s*hub|knowledge\s*root|moc|map)\b/i;
 const hashText = (value) => Array.from(value).reduce((hash, char) => ((hash << 5) - hash + char.charCodeAt(0)) | 0, 0);
 const jitter = (value, range) => {
     const normalized = Math.abs(hashText(value) % 1000) / 1000;
@@ -62,6 +63,44 @@ const byDegreeThenTitle = (degrees) => (left, right) => {
     const degreeDelta = (degrees.get(right.id) ?? 0) - (degrees.get(left.id) ?? 0);
     return degreeDelta === 0 ? byTitle(left, right) : degreeDelta;
 };
+const hubScore = (node) => {
+    const title = node.title.trim().toLowerCase();
+    if (title === 'memory hub')
+        return 5;
+    if (title === 'knowledge root')
+        return 4;
+    if (/\bmoc\b/i.test(node.title))
+        return 3;
+    return hubTitlePattern.test(node.title) ? 2 : 0;
+};
+const selectPrimaryHubId = (nodes, degrees) => {
+    const ranked = [...nodes]
+        .filter((node) => hubScore(node) > 0)
+        .sort((left, right) => {
+        const scoreDelta = hubScore(right) - hubScore(left);
+        if (scoreDelta !== 0)
+            return scoreDelta;
+        const degreeDelta = (degrees.get(right.id) ?? 0) - (degrees.get(left.id) ?? 0);
+        if (degreeDelta !== 0)
+            return degreeDelta;
+        return left.title.localeCompare(right.title);
+    });
+    return ranked[0]?.id ?? null;
+};
+const centerLayoutByNode = (nodes, nodeId) => {
+    if (!nodeId) {
+        return nodes;
+    }
+    const anchor = nodes.find((node) => node.id === nodeId);
+    if (!anchor) {
+        return nodes;
+    }
+    return nodes.map((node) => ({
+        ...node,
+        x: node.x - anchor.x,
+        y: node.y - anchor.y
+    }));
+};
 const naturalSegmentSeed = (node) => groupKey(node) === '00-maps' || /\b(moc|map)\b/i.test(node.title);
 const segmentName = (node) => node.title.replace(/^MOC\s+/i, '').replace(/\s+Memory Map$/i, '').trim() || node.title;
 const collectComponent = (adjacency, startId, visited) => {
@@ -128,13 +167,17 @@ const groupNodesBySegment = (nodes, segments) => {
     return new Map(groups);
 };
 const segmentAngle = (segment, index, count) => segmentAngles[segment] ?? (Math.PI * 2 * index) / Math.max(count, 1) - Math.PI / 2;
+const petalSpreadForSegmentSize = (size) => {
+    const safeSize = Math.max(size, 1);
+    return 180 + Math.log2(safeSize + 1) * 6;
+};
 const createSegmentNodes = (segments, degrees, segmentCount) => ([segment, nodes], segmentIndex) => {
     const sortedNodes = [...nodes].sort(byDegreeThenTitle(degrees));
     const angle = segmentAngle(segment, segmentIndex, segmentCount);
     const baseRadius = segmentCount === 1 ? 0 : 340 + Math.min(sortedNodes.length, 22) * 10;
     const centerX = Math.cos(angle) * baseRadius;
     const centerY = Math.sin(angle) * (baseRadius * 0.78);
-    const petalSpread = 40 + Math.sqrt(sortedNodes.length) * 14;
+    const petalSpread = petalSpreadForSegmentSize(sortedNodes.length);
     return sortedNodes.map((node, index) => {
         const localAngle = index * 2.399963 + jitter(node.title, 0.42);
         const localRadius = Math.sqrt(index + 1) * petalSpread;
@@ -246,8 +289,10 @@ export const createCauliflowerGraphLayout = (graph) => {
     const segmentGroups = Array.from(groupNodesBySegment(graph.nodes, segments).entries())
         .sort(([left], [right]) => left.localeCompare(right));
     const nodes = relaxCollisions(segmentGroups.flatMap(createSegmentNodes(segments, degrees, segmentGroups.length)));
+    const primaryHubId = selectPrimaryHubId(graph.nodes, degrees);
+    const centeredNodes = centerLayoutByNode(nodes, primaryHubId);
     return {
-        nodes,
+        nodes: centeredNodes,
         edges: graph.edges
     };
 };

package/dist/domain/middle-out.js

@@ -0,0 +1,18 @@
+export const middleOutIndices = (size, pivotIndex) => {
+    if (!Number.isFinite(size) || size <= 0) {
+        return [];
+    }
+    const clampedPivot = Math.max(0, Math.min(Math.floor(pivotIndex), size - 1));
+    const indices = [clampedPivot];
+    for (let offset = 1; indices.length < size; offset += 1) {
+        const left = clampedPivot - offset;
+        const right = clampedPivot + offset;
+        if (left >= 0) {
+            indices.push(left);
+        }
+        if (right < size) {
+            indices.push(right);
+        }
+    }
+    return indices;
+};

package/dist/infrastructure/config.js

@@ -15,6 +15,13 @@ export const defaultBrainlinkConfig = {
     embeddingProvider: 'local',
     defaultSearchMode: 'hybrid',
     chunkSize: 1200,
+    searchPack: {
+        rowChunkSize: 5_000,
+        compressionLevel: 5,
+        useDictionary: true,
+        guardrailMinSavingsPercent: 8,
+        guardrailMaxLatencyRegressionPercent: 5
+    },
     agentProfiles: {}
 };
 const configFilenames = ['brainlink.config.json', '.brainlink.json'];
@@ -37,6 +44,36 @@ const sanitizeEmbeddingProvider = (value) => typeof value === 'string' && embedd
 export const sanitizeSearchMode = (value, fallback = defaultBrainlinkConfig.defaultSearchMode) => typeof value === 'string' && searchModes.has(value) ? value : fallback;
 const sanitizeAllowedVaults = (value) => Array.isArray(value) ? value.filter((item) => typeof item === 'string' && item.trim().length > 0) : [];
 const sanitizePositiveNumber = (value) => typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : undefined;
+const sanitizeIntegerInRange = (value, fallback, minimum, maximum) => {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return fallback;
+    }
+    const rounded = Math.round(value);
+    if (rounded < minimum) {
+        return minimum;
+    }
+    if (rounded > maximum) {
+        return maximum;
+    }
+    return rounded;
+};
+const sanitizeSearchPackConfig = (value) => {
+    const fallback = defaultBrainlinkConfig.searchPack;
+    if (!isRecord(value)) {
+        return fallback;
+    }
+    return {
+        rowChunkSize: sanitizeIntegerInRange(value.rowChunkSize, fallback.rowChunkSize, 100, 100_000),
+        compressionLevel: sanitizeIntegerInRange(value.compressionLevel, fallback.compressionLevel, 0, 11),
+        useDictionary: typeof value.useDictionary === 'boolean' ? value.useDictionary : fallback.useDictionary,
+        guardrailMinSavingsPercent: typeof value.guardrailMinSavingsPercent === 'number' && Number.isFinite(value.guardrailMinSavingsPercent)
+            ? Math.max(0, Math.min(95, value.guardrailMinSavingsPercent))
+            : fallback.guardrailMinSavingsPercent,
+        guardrailMaxLatencyRegressionPercent: typeof value.guardrailMaxLatencyRegressionPercent === 'number' && Number.isFinite(value.guardrailMaxLatencyRegressionPercent)
+            ? Math.max(0, Math.min(300, value.guardrailMaxLatencyRegressionPercent))
+            : fallback.guardrailMaxLatencyRegressionPercent
+    };
+};
 const sanitizeAgentProfile = (value) => {
     if (!isRecord(value)) {
         return null;
@@ -130,6 +167,7 @@ const sanitizeConfig = (value) => ({
         : defaultBrainlinkConfig.defaultContextTokens,
     allowedVaults: [...sanitizeAllowedVaults(value.allowedVaults), ...readAllowedVaultsFromEnv()],
     chunkSize: typeof value.chunkSize === 'number' && value.chunkSize > 0 ? value.chunkSize : defaultBrainlinkConfig.chunkSize,
+    searchPack: sanitizeSearchPackConfig(value.searchPack),
     embeddingProvider: sanitizeEmbeddingProvider(value.embeddingProvider),
     defaultSearchMode: sanitizeSearchMode(value.defaultSearchMode),
     agentProfiles: sanitizeAgentProfiles(value.agentProfiles)

package/dist/infrastructure/file-index.js

@@ -0,0 +1,358 @@
+import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { cosineSimilarity } from '../domain/embeddings.js';
+const queryTokenPattern = /[\p{L}\p{N}_-]+/gu;
+const indexCacheMaxEntries = 16;
+const indexCache = new Map();
+const emptyIndex = () => ({
+    version: 1,
+    updatedAt: new Date().toISOString(),
+    documents: [],
+    chunks: [],
+    links: []
+});
+export const indexStoragePath = (vaultPath) => join(vaultPath, '.brainlink', 'index.json');
+const readIndex = async (vaultPath) => {
+    const path = indexStoragePath(vaultPath);
+    let stats = null;
+    try {
+        const fileStats = await stat(path);
+        stats = { mtimeMs: fileStats.mtimeMs, size: fileStats.size };
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            indexCache.delete(path);
+            return emptyIndex();
+        }
+        return emptyIndex();
+    }
+    const cached = indexCache.get(path);
+    if (cached && cached.mtimeMs === stats.mtimeMs && cached.size === stats.size) {
+        return cached.index;
+    }
+    try {
+        const parsed = JSON.parse(await readFile(path, 'utf8'));
+        const loaded = {
+            version: 1,
+            updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date().toISOString(),
+            documents: Array.isArray(parsed.documents) ? parsed.documents : [],
+            chunks: Array.isArray(parsed.chunks) ? parsed.chunks : [],
+            links: Array.isArray(parsed.links) ? parsed.links : []
+        };
+        indexCache.set(path, { ...stats, index: loaded });
+        if (indexCache.size > indexCacheMaxEntries) {
+            const oldest = indexCache.keys().next().value;
+            if (typeof oldest === 'string') {
+                indexCache.delete(oldest);
+            }
+        }
+        return loaded;
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            indexCache.delete(path);
+            return emptyIndex();
+        }
+        return emptyIndex();
+    }
+};
+const writeIndex = async (vaultPath, index) => {
+    const target = indexStoragePath(vaultPath);
+    const temp = `${target}.tmp`;
+    await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+    await writeFile(temp, `${JSON.stringify(index)}\n`, { encoding: 'utf8', mode: 0o600 });
+    await rename(temp, target);
+    const fileStats = await stat(target);
+    indexCache.set(target, {
+        mtimeMs: fileStats.mtimeMs,
+        size: fileStats.size,
+        index
+    });
+};
+const normalizeToken = (value) => value
+    .normalize('NFKD')
+    .replace(/\p{Diacritic}/gu, '')
+    .toLowerCase();
+const tokenize = (query) => query
+    .match(queryTokenPattern)
+    ?.map(normalizeToken)
+    .filter((token) => token.length > 1) ?? [];
+const countOccurrences = (text, token) => {
+    let hits = 0;
+    let cursor = 0;
+    while (cursor < text.length) {
+        const index = text.indexOf(token, cursor);
+        if (index < 0) {
+            break;
+        }
+        hits += 1;
+        cursor = index + token.length;
+    }
+    return hits;
+};
+const textScore = (row, tokens) => {
+    if (tokens.length === 0) {
+        return 0;
+    }
+    const title = normalizeToken(row.title);
+    const path = normalizeToken(row.path);
+    const content = normalizeToken(row.content);
+    const tags = normalizeToken(row.tags.join(' '));
+    return tokens.reduce((score, token) => {
+        const titleHits = countOccurrences(title, token);
+        const tagHits = countOccurrences(tags, token);
+        const pathHits = countOccurrences(path, token);
+        const contentHits = countOccurrences(content, token);
+        return score + titleHits * 5 + tagHits * 4 + pathHits * 2 + Math.min(contentHits, 6);
+    }, 0);
+};
+const semanticScore = (row, queryEmbedding) => queryEmbedding.length > 0 && row.embedding.length > 0 ? cosineSimilarity(queryEmbedding, row.embedding) : 0;
+const toResult = (row, mode, text, semantic) => {
+    const score = mode === 'fts' ? text : mode === 'semantic' ? semantic : text + semantic * 8;
+    return {
+        documentId: row.documentId,
+        agentId: row.agentId,
+        title: row.title,
+        path: row.path,
+        chunkId: row.chunkId,
+        chunkOrdinal: row.chunkOrdinal,
+        content: row.content,
+        score,
+        textScore: text,
+        semanticScore: semantic,
+        searchMode: mode,
+        tags: row.tags
+    };
+};
+const toGraphLink = (link, documentsById) => {
+    const source = documentsById.get(link.fromDocumentId);
+    const target = link.toDocumentId ? documentsById.get(link.toDocumentId) : undefined;
+    return {
+        agentId: source?.agentId ?? 'shared',
+        fromTitle: source?.title ?? 'Unknown',
+        fromPath: source?.path ?? 'Unknown',
+        toTitle: target?.title ?? link.toTitle,
+        toPath: target?.path ?? null,
+        weight: link.weight,
+        priority: link.priority
+    };
+};
+export const openFileIndex = (vaultPath) => {
+    const load = async () => readIndex(vaultPath);
+    const persist = async (index) => writeIndex(vaultPath, index);
+    return {
+        reset: async () => {
+            await persist(emptyIndex());
+        },
+        saveDocuments: async (documents) => {
+            const chunks = documents.flatMap((document) => document.chunks);
+            const links = documents.flatMap((document) => document.links);
+            await persist({
+                version: 1,
+                updatedAt: new Date().toISOString(),
+                documents: documents.map((document) => document.document),
+                chunks,
+                links
+            });
+        },
+        getIndexedDocuments: async (agentId) => {
+            const index = await load();
+            const documents = agentId ? index.documents.filter((document) => document.agentId === agentId) : index.documents;
+            const selectedDocumentIds = new Set(documents.map((document) => document.id));
+            const chunksByDocumentId = index.chunks.reduce((state, chunk) => {
+                if (!selectedDocumentIds.has(chunk.documentId)) {
+                    return state;
+                }
+                const current = state.get(chunk.documentId) ?? [];
+                current.push(chunk);
+                state.set(chunk.documentId, current);
+                return state;
+            }, new Map());
+            const linksByDocumentId = index.links.reduce((state, link) => {
+                if (!selectedDocumentIds.has(link.fromDocumentId)) {
+                    return state;
+                }
+                const current = state.get(link.fromDocumentId) ?? [];
+                current.push(link);
+                state.set(link.fromDocumentId, current);
+                return state;
+            }, new Map());
+            return documents
+                .map((document) => ({
+                document,
+                chunks: [...(chunksByDocumentId.get(document.id) ?? [])].sort((left, right) => left.ordinal - right.ordinal),
+                links: linksByDocumentId.get(document.id) ?? []
+            }))
+                .sort((left, right) => left.document.path.localeCompare(right.document.path));
+        },
+        search: async (query, limit, agentId, mode = 'hybrid', queryEmbedding = []) => {
+            const index = await load();
+            const documentsById = new Map(index.documents.map((document) => [document.id, document]));
+            const rows = index.chunks.flatMap((chunk) => {
+                const document = documentsById.get(chunk.documentId);
+                if (!document) {
+                    return [];
+                }
+                if (agentId && document.agentId !== agentId) {
+                    return [];
+                }
+                return [
+                    {
+                        documentId: document.id,
+                        agentId: document.agentId,
+                        title: document.title,
+                        path: document.path,
+                        chunkId: chunk.id,
+                        chunkOrdinal: chunk.ordinal,
+                        content: chunk.content,
+                        tags: document.tags,
+                        embedding: chunk.embedding
+                    }
+                ];
+            });
+            const tokens = tokenize(query);
+            const results = rows
+                .map((row) => {
+                const text = textScore(row, tokens);
+                const semantic = semanticScore(row, queryEmbedding);
+                return toResult(row, mode, text, semantic);
+            })
+                .filter((row) => row.score > 0 || tokens.length === 0)
+                .sort((left, right) => right.score - left.score || left.title.localeCompare(right.title))
+                .slice(0, Math.max(0, limit));
+            return results;
+        },
+        listLinks: async (agentId) => {
+            const index = await load();
+            const documentsById = new Map(index.documents.map((document) => [document.id, document]));
+            return index.links
+                .filter((link) => {
+                const source = documentsById.get(link.fromDocumentId);
+                return agentId ? source?.agentId === agentId : true;
+            })
+                .map((link) => toGraphLink(link, documentsById))
+                .sort((left, right) => left.fromTitle.localeCompare(right.fromTitle));
+        },
+        listBacklinks: async (title, agentId) => {
+            const index = await load();
+            const titleKey = title.toLowerCase();
+            const documentsById = new Map(index.documents.map((document) => [document.id, document]));
+            return index.links
+                .filter((link) => link.toTitle.toLowerCase() === titleKey)
+                .filter((link) => {
+                const source = documentsById.get(link.fromDocumentId);
+                return agentId ? source?.agentId === agentId : true;
+            })
+                .map((link) => toGraphLink(link, documentsById))
+                .sort((left, right) => right.weight - left.weight || left.fromTitle.localeCompare(right.fromTitle));
+        },
+        getGraph: async (agentId) => {
+            const index = await load();
+            const documents = agentId ? index.documents.filter((document) => document.agentId === agentId) : index.documents;
+            const documentIds = new Set(documents.map((document) => document.id));
+            const edges = index.links
+                .filter((link) => documentIds.has(link.fromDocumentId))
+                .map((link) => ({
+                source: link.fromDocumentId,
+                target: link.toDocumentId,
+                targetTitle: link.toTitle,
+                weight: link.weight,
+                priority: link.priority
+            }));
+            return {
+                nodes: documents.map((document) => ({
+                    id: document.id,
+                    agentId: document.agentId,
+                    title: document.title,
+                    path: document.path,
+                    content: document.content,
+                    tags: document.tags
+                })),
+                edges
+            };
+        },
+        getGraphSummary: async (agentId) => {
+            const graph = await (async () => {
+                const index = await load();
+                const documents = agentId ? index.documents.filter((document) => document.agentId === agentId) : index.documents;
+                const documentIds = new Set(documents.map((document) => document.id));
+                const edges = index.links
+                    .filter((link) => documentIds.has(link.fromDocumentId))
+                    .map((link) => ({
+                    source: link.fromDocumentId,
+                    target: link.toDocumentId,
+                    targetTitle: link.toTitle,
+                    weight: link.weight,
+                    priority: link.priority
+                }));
+                return {
+                    nodes: documents.map((document) => ({
+                        id: document.id,
+                        agentId: document.agentId,
+                        title: document.title,
+                        path: document.path,
+                        content: '',
+                        tags: document.tags
+                    })),
+                    edges
+                };
+            })();
+            return graph;
+        },
+        getGraphNode: async (id, agentId) => {
+            const index = await load();
+            const document = index.documents.find((row) => row.id === id && (!agentId || row.agentId === agentId));
+            return document
+                ? {
+                    id: document.id,
+                    agentId: document.agentId,
+                    title: document.title,
+                    path: document.path,
+                    content: document.content,
+                    tags: document.tags
+                }
+                : undefined;
+        },
+        searchGraphNodeIds: async (query, limit, agentId) => {
+            const index = await load();
+            const normalized = normalizeToken(query);
+            if (normalized.length === 0 || limit <= 0) {
+                return [];
+            }
+            const tokens = tokenize(query);
+            const scored = index.documents
+                .filter((document) => (!agentId || document.agentId === agentId))
+                .map((document) => {
+                const score = textScore({
+                    documentId: document.id,
+                    agentId: document.agentId,
+                    title: document.title,
+                    path: document.path,
+                    chunkId: document.id,
+                    chunkOrdinal: 0,
+                    content: document.content,
+                    tags: document.tags,
+                    embedding: []
+                }, tokens);
+                return { id: document.id, score };
+            })
+                .filter((row) => row.score > 0)
+                .sort((left, right) => right.score - left.score || left.id.localeCompare(right.id))
+                .slice(0, limit);
+            return scored.map((row) => row.id);
+        },
+        listAgents: async () => {
+            const index = await load();
+            const counts = index.documents.reduce((state, document) => {
+                state.set(document.agentId, (state.get(document.agentId) ?? 0) + 1);
+                return state;
+            }, new Map());
+            return Array.from(counts.entries())
+                .sort((left, right) => left[0].localeCompare(right[0]))
+                .map(([id, documentCount]) => ({ id, documentCount }));
+        },
+        close: () => {
+            // File-based index has no persistent connection.
+        }
+    };
+};

package/dist/infrastructure/file-system-vault.js

@@ -76,6 +76,21 @@ export const readMarkdownFiles = async (vaultPath) => {
         };
     }));
 };
+export const readMarkdownFileSummaries = async (vaultPath) => {
+    const absoluteVaultPath = await ensureVault(vaultPath);
+    const paths = await walkMarkdownFiles(absoluteVaultPath);
+    const summaries = await Promise.all(paths.map(async (absolutePath) => {
+        const fileStats = await stat(absolutePath);
+        return {
+            absolutePath,
+            relativePath: relative(absoluteVaultPath, absolutePath),
+            createdAt: fileStats.birthtime,
+            updatedAt: fileStats.mtime,
+            size: fileStats.size
+        };
+    }));
+    return summaries.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+};
 export const listVaultFiles = async (vaultPath) => {
     const absoluteVaultPath = await ensureVault(vaultPath);
     return walkVaultFiles(absoluteVaultPath);

package/dist/infrastructure/index-state.js

@@ -0,0 +1,56 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const indexStateFileName = 'index-state.json';
+const toIndexStatePath = (vaultPath) => join(vaultPath, '.brainlink', indexStateFileName);
+export const readIndexState = async (vaultPath) => {
+    try {
+        const parsed = JSON.parse(await readFile(toIndexStatePath(vaultPath), 'utf8'));
+        if (parsed.version !== 1 || !Array.isArray(parsed.files)) {
+            return null;
+        }
+        const files = parsed.files.flatMap((entry) => {
+            if (!entry || typeof entry !== 'object') {
+                return [];
+            }
+            const row = entry;
+            if (typeof row.path !== 'string' || typeof row.mtimeMs !== 'number' || typeof row.size !== 'number') {
+                return [];
+            }
+            return [
+                {
+                    path: row.path,
+                    mtimeMs: row.mtimeMs,
+                    size: row.size
+                }
+            ];
+        });
+        return {
+            version: 1,
+            updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date().toISOString(),
+            chunkSize: typeof parsed.chunkSize === 'number' ? parsed.chunkSize : 1200,
+            embeddingProvider: typeof parsed.embeddingProvider === 'string' ? parsed.embeddingProvider : 'none',
+            searchPackRowChunkSize: typeof parsed.searchPackRowChunkSize === 'number' ? parsed.searchPackRowChunkSize : 5_000,
+            searchPackCompressionLevel: typeof parsed.searchPackCompressionLevel === 'number' ? parsed.searchPackCompressionLevel : 5,
+            searchPackUseDictionary: typeof parsed.searchPackUseDictionary === 'boolean' ? parsed.searchPackUseDictionary : true,
+            files,
+            pendingPackChanges: typeof parsed.pendingPackChanges === 'number' && parsed.pendingPackChanges >= 0 ? parsed.pendingPackChanges : 0
+        };
+    }
+    catch {
+        return null;
+    }
+};
+export const writeIndexState = async (vaultPath, state) => {
+    const payload = {
+        version: 1,
+        updatedAt: new Date().toISOString(),
+        chunkSize: state.chunkSize,
+        embeddingProvider: state.embeddingProvider,
+        searchPackRowChunkSize: state.searchPackRowChunkSize,
+        searchPackCompressionLevel: state.searchPackCompressionLevel,
+        searchPackUseDictionary: state.searchPackUseDictionary,
+        files: [...state.files].sort((left, right) => left.path.localeCompare(right.path)),
+        pendingPackChanges: Math.max(0, Math.floor(state.pendingPackChanges))
+    };
+    await writeFile(toIndexStatePath(vaultPath), `${JSON.stringify(payload)}\n`, 'utf8');
+};